The ChatServer Suite

This document describes the Apple Events supported by TeleFinder Server's ChatServer in versions 4.0 and 5.0.

This information may be of use to programmers wishing to develop software that works with TeleFinder. Please be aware that this information is dynamic and subject to change.

Event Descriptions



Login

This event opens a virtual session with ChatServer. To further refer to this session, a session ID is returned. Login does not mean that the user is opening chat. It only means that the user is logged onto the host. ChatServer does need to know this to be able to send chat invitations.

Event Class kChatEventClass

Event ID kLoginEvent

Parameters

kUserItem --A string containing the username under which the session is opened. Up to 31 characters.

Descriptor Type: typeChar
Required or Optional? Required

kStatItem -- A string containing the line name under which the session is opened. Up to 31 characters.
Descriptor Type: typeChar
Required or Optional? Required

kQuietItem -- True if the user cannot receive say or whisper events. It means that the user cannot use chat.
Descriptor Type: typeSMInt
Required or Optional? Required



Reply Parameters

kSIDItem --A longword containing the session ID

Descriptor Type: typeLong

Result Codes Operating system error or zero for successful connection


Logout

This event closes a session previously opened with Login. The session ID is then no longer valid.

Event Class kChatEventClass

Event ID kLogoutEvent

Parameters

kSIDItem -- A longword containing the session ID

Descriptor Type: typeLong
Required or Optional? Required


Reply Parameters None


Result Codes Operating system error or zero for successful connection


Enter Chat

This event should be called when the user enters Chatting mode ( able to enter chat rooms and receiv Instant Messages ).


Event Class kChatEventClass

Event ID kEnterChatEvent

Parameters

kSIDItem --A longword containing the session ID

Descriptor Type: typeLong
Required or Optional? Required

kChannelItem -- The channel to tune into.

Descriptor Type: typeLong
Required or Optional? Optional

Reply Parameters

kMessageItem A welcome message* (can be empty)
Descriptor Type: typeChar


Result Codes Operating system error or zero for successful connection

* TeleFinder does not use the welcome message.


Leave Chat

This event should be called when the user is leaving chatting mode.

Event Class kChatEventClass

Event ID kLeaveChatEvent

kSIDItem
-- A longword containing
the session ID
Descriptor Type: typeLong
Required or Optional? Required

Reply Parameters

kMessageItem --A goodbye message* (can be empty)
Descriptor Type: typeChar


Result Codes Operating system error or zero for successful connection.


* TeleFinder does not use the welcome message.

ChangeChannel

This event does change the chatting channel used in ChatServer. This is how TeleFinder moves users from room to room as they open and close various chat areas.


Event Class kChatEventClass

Event ID kChangeChannelEvent

Parameters

kSIDItem -- the session ID

Descriptor Type: typeLong
Required or Optional? Required

kChannelItem
the channel to tune into

Descriptor Type: typeLong
Required or Optional? Required

Reply Parameters

kMessageItem -- A welcome message which is attached to the channel (can be empty)*
Descriptor Type: typeChar

kChannelItem the channel tuned into should be the same as passed but might be another one in case of errors.

Descriptor Type: typeLong

Result Codes Operating system error or zero for successful connection

* TeleFinder does not use the welcome message.


GetUserList

This event returns a structure which contains a list of all users currently logged onto the BBS.

Event Class kChatEventClass

Event ID kGetUserListEvent

Parameters

kSIDItem -- the session ID
Descriptor Type: typeLong
Required or Optional? Required

kChannelItem -- The channel to get the list of. Pass -1L to get a list of all users logged in.
Descriptor Type: typeLong
Required or Optional? Optional, returns all users online if you do not specify a channel.


Reply Parameters None

kUserInfoItem -- An array of "ChatUserInfo" records.
Descriptor Type: keyDirectObject



typedef struct ChatUserInfo
{
Byte name[32]; // Pascal String user name
Byte sourceName[32]; // Pascal String bbs node name
unsigned long loginTime;
unsigned long chatState;
} ChatUserInfo;

typedef ChatUserInfo *ChatUserInfoPtr, **ChatUserInfoHandle;


Result Codes Operating system error or zero for successful connection

Say

This event sends a user's message to the users on a channel. The say event is then transmitted to all the listeners on your current channel by the SayUser event. This event is only valid after you send a "ChangeChannel" event.


Event Class kChatEventClass

Event ID kClientSayEvent

Parameters

kSIDItem -- the session ID
Descriptor Type: typeLong
Required or Optional? Required

kMessageItem -- the message to say, up to 1K
Descriptor Type: typeChar
Required or Optional? Required


Reply Parameters none


Result Codes Operating system error or zero for successful connection.


Say to User

This event sends chat room messages back to the users on the channel. You will not receive your own messages by this event.

Event Class kChatEventClass

Event ID kSayEvent

Parameters

kMessageItem -- the message to say, up to 1K
Descriptor Type: typeChar
Required or Optional? Required


Reply Parameters none


Result Codes Operating system error or zero for successful connection.


Instant Message

This event sends an Instant Message from a user to a specific other user. That user can be on another channel. This event is used by TeleFinder to send Instant Messages to a user online.

Event Class kChatEventClass

Event ID kCSWhisper

Parameters

kSIDItem -- The session ID
Descriptor Type: typeLong
Required or Optional? Required

kMessageItem -- The message to display
Descriptor Type: typeChar
Required or Optional? Required

kUserItem -- The name of the user that the message is from, as a Pascal string.
Descriptor Type: typeChar
Required or Optional? Required



Reply Parameters none


Result Codes Operating system error or zero for successful connection.


Send Instant Message

Clients use this event to send an Instant message to another user that is online. This event sends a private message from a user to a specific other user. That user can be on another channel.

Event Class kChatEventClass

Event ID kCSWhisper

Parameters

kSIDItem -- Your session ID
Descriptor Type: typeLong
Required or Optional? Required

kMessageItem -- The message to say
Descriptor Type: typeChar
Required or Optional? Required

kUserItem -- The name of the user, as a Pascal string.
Descriptor Type: typeChar
Required or Optional? Required



Reply Parameters none


Result Codes Operating system error or zero for successful connection.


StatusHasEnteredChannel

This event is only received from the server and tells you that someone has tuned into the channel you are in.

Event Class kChatEventClass

Event ID kStatusHasEnteredChannelEvent

Parameters received


kSIDItem -- the client's session ID
Descriptor Type: typeLong


kUserItem -- the username which tuned in
Descriptor Type: typeChar


StatusHasLeftChannel

This event is only received from the server and tells you that someone has left the channel you are currently in.

Event Class kChatEventClass

Event ID kStatusHasLeftChannelEvent

Parameters received

kSIDItem -- the client's session ID
Descriptor Type: typeLong

kUserItem -- the username which left the channel
Descriptor Type: typeChar


Constants defined in the ChatServer Suite

/* ChatServerSuite.h */
/* Apple Event definitions */

#pragma once

#define kChatEventClass 'chat'

// client sends this version now starting w/ 4.0
#define kClientSayEvent 'cTel'
#define kClientWhisperEvent 'cWhs'

#define kSayEvent 'tell'
#define kSayUserEvent 'tel2' /* added to support SayUser event */

#define kWhisperEvent 'whis'
#define kRingEvent 'ring'
#define kStatusHasEnteredChatEvent 'Echt'
#define kStatusHasLeftChatEvent 'Lcht'
#define kStatusHasEnteredChannelEvent 'Echn'
#define kStatusHasLeftChannelEvent 'Lchn'

#define kStatusLoginEvent 'Esys'
#define kStatusLogoutEvent 'Lsys'


#define kLoginEvent 'Lin '
#define kLogoutEvent 'Lout'
#define kEnterChatEvent 'Entr'
#define kLeaveChatEvent 'Leav'
#define kChangeChannelEvent 'CgCh'
#define kGetUserListEvent 'gusr'
#define kAdminEvent 'Admi'

#define kMessageItem 'cMsg'
#define kChannelItem 'chch'
#define kSIDItem 'sid '
#define kUserItem 'user'
#define kStatItem 'stat'
#define kQuietItem 'kyat'

#define kUserInfoItem 'uifo' // for users online list, or users in room


Session Handling

This part defines how sessions should be handled.

Login and Logout must be sent at Login/Logout time, even if the user
does not want to use chat.

When the user wants to chat, you should send a EnterChat event (TeleFinder does this upon login). Now you can Send Instant Messages and Enter chat rooms.

Send a ChangeChannel event when you want to enter a chat room. If you do not use the ChangeChannel, you will be on channel -1 which is a 'dummy' channel.

In a Chat Room you will get Status events telling you that other users coming in or leaving channels or the chat. You will get SayUser and Instant Message events too.

Leaving the chat using LeaveChat will disable all those events and reelable Ring.
Logout will disable Ring again.

Status messages generated by yourself because of entering/leaving the chat or
a specific channel will not be sent to yourself (i. e. the session that generated those events).

(c) Copyright 1996 , Spider Island Software, All Rights Reserved Updated: February 29, 1996
 

TeleFinder 5.7 Server is used by no panty Brittany Spears to serve her MP3 files

TeleFinder Taxi takes you homeBuy a Book!