CR Native Code Interface

Copyright (C) 1999-2000, WebMaster, Incorporated
$Id: CRNative.txt,v 1.3 2001/08/07 10:36:34 cvs Exp $

The Enterprise Edition of ConferenceRoom supports an interface to allow custom code to interface with the chat server directly. For UNIX platforms, the custom code must be supplied in the form of a shared object (.so) file. For WIN32 platforms, the custom code must be supplied in the form of a DLL file.

The following warnings should be kept in mind: Bugs in your custom code can destabilize the chat server or cause it to crash. ConferenceRoom is multithreaded and your code must be thread-safe. If your code is not re-entrant, you must protect it with mutexes or critical sections.

ConferenceRoom will call your code with as few locks as possible held. Normally ConferenceRoom will, at most, lock a single user's connection while your code is running. This enhances performance, but has some side-effects.

Suppose a user attempts to join a channel and you have hooked AuthenticeJoin. While your code is running, only that single user's connection is locked, so an operator could kill that user while your code is running. In this case, even if you return the correct code to let the user join the channel, the user will not wind up joining the channel since he's not on the server anymore.

On UNIX platforms, you may use C or C++ to create your code. On WIN32 platforms, you may use any language that makes it possible to create a DLL, but Visual C++ 5.0 or later is highly recommended.

You must command ConferenceRoom to separately hook each function you wish to intercept. If the same object file hooks more than one function, it will only be loaded/initalized once.

Callbacks are functions in CR that your code can call. Callouts are functions in your code that CR can call. Callouts must be configured in CR. You may use any callbacks you want without any special configuration.

You configure a callout with the command (from a chat client with administrative privileges):

/AS function <CallOutName> add <FileName>.<extension>

The file must be in a directory called lib under the master ConferenceRoom directory (the one with the programs directory under it. Note that if a function is already hooked (even if unsuccessful), you must unhook it first with:

/AS function <CallOutName> del

The following callbacks are currently defined:

DoDebug: This command adds an entry to ConferenceRoom's debug log. This is not normally useful except if you are trying to debug ConferenceRoom itself. Normally you should write debug information to your own file.

LockModule: Increments a module's usage count, preventing ConferenceRoom from unloading it. If you, for example, create your own thread, you should call this function because you do not want ConferenceRoom to unload your module while a thread is running in it -- that would be disastrous.

UnlockModule: Decrements your module's usage count.

GetTime: This gets ConferenceRoom's server time. This may differ from the system time for a variety of reasons. This time is guaranteed never to decrement and is guaranteed not to skip over any time values.

DoAS: This callback executes an AS command as if an administrator typed it in. You leave off the as part.

The following callouts are currently defined:

AuthenticateUser: This callout will be called every time a new user signs on to the server or a current local user changes nicknames. The connect/change can be allowed or disallowed and a message sent to the user.

AuthenticateJoin: This callout will be called every time a local user attempts to join a channel. The join can be allowed or disallowed and a message can be sent to the user.

DisconnectUser: This function allows a user who signs on to disconnect a previously-existing user with the same nickname.

Command: This callout will be called every time a client uses the 'CMD' command. It is used to provide a way to pass information from chat clients to custom code for logging or other purposes. A message can be returned in the form of a 780 numeric. This can be used in conjunction with the DoAS callback to provide for remotely controlled server configuration changes. This can also be used as a way of implementing custom commands or logging.

CreateChannel: This callout will be called every time a local client attempts to create a new channel (by joining an empty channel). The creation can be permitted or refused.

UserParted: This is a logging function that will be called to report that a local user has left a channel (by any means).

For more information, see the sample native interface code. If you don't have the sample native interface code, contact WebMaster Support. If you have any questions about the ConferenceRoom native code interface, please contact WebMaster Support at support@webmaster.com

For more information, see the sample native interface code sample.cpp