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
