ShowTable of Contents
Anbuchezhian Balakrishnan
Software Engineer
IBM Software Group
Dublin Software Lab
Mulhuddart, Dublin, Ireland
February 2010
Summary: Learn all about the IBM® Lotus® Sametime® 8.0.x and 8.5 chat logging, its API, and how to extend the new features through a sample DLL developed based on the Sametime 8.0.1 Software Development Kit(SDK). This article is intended for users at the Intermediate level who have good, basic knowledge of Lotus Sametime.
Table of Contents
1 Introduction
2 Chat logging basics
2.1 Modes and implementations of chat logging
3 Enabling chat logging
4 Chat logging SPI
4.1 Chat logging SPI contents
5 Considerations and limitations
6 Building and installing a chat logging DLL for Windows
6.1 Building and Installing a chat-logging shared library for Linux
7 Chat logging SPI sample
7.1 Sametime.ini flags for the SPI sample
8 Chat logging SPI sample parameters
8.1 Chat logging SPI sample code
8.2 Chat logging SPI functions
9 Error handling
9.1 Prevent chats between two users using the SPI function
10 Conclusion
11 Resources
1 Introduction
Lotus Sametime chat logging is an important feature of the Sametime server, providing the ability to intercept all chat conversations at the server, including two-way chat and
n-way chat, and to store a record of them in a data store for future retrieval and reference.
Lotus Sametime also provides a set of APIs -- the Sametime Chat Logging Server Provider Interface (SPI) – with which developers can extend the chat logging feature. Specifically,they can implement their own DLL based on these APIs to handle the chat conversation on the server side, such as storing the conversation in the Domino database.
Sametime 8.0.1 added some new features for the chat logging application, including content filters for instant messages and the ability to block session creation. For example, using content filters, the user can define some sensitive words, and the chat logging application will filter these pre-defined words and give a warning message or break off the chat conversation if they are found. Also, if the user defines a group of users, chat logging will forbid a chat conversation with these users or among them.
Record keeping and archiving practices are becoming pivotal in corporate enterprises. A corporation may want to record all types of communication, including Sametime chat sessions, for reasons such as:
•Regulatory compliance
•Collaborative commerce rules and work flow
•Corporate and public sector governance
•Appropriate use review
Introduced in Sametime 2.5, the chat logging application is an excellent way to record chat logs during two-way or
n-way chat sessions. The chat messages are archived on the Sametime server and can be retrieved for future reference.
2 Chat logging basics
As mentioned above, Sametime chat logging can be enabled on two types of Sametime text messages:
One-to-one instant messages
n-way chats
The Sametime server implements two methods for processing chats:
•Instant messaging (one-to-one instant messages):
Basic, one-to-one IMs are connected by the servers, and at that point the servers simply act as routers for encrypted (by default) messages. In one-to-one instant sessions, the chats are logged on the home Sametime server of the user (recipient)who accepts the chat invite.
•n-way chats:
n-way chats implement a mechanism called a place, to exchange messages among multiple participants. Here, the chats are logged on the server that is handling the place.
Either type of message traffic can be intercepted by a chat recorder built-in provided by Lotus Sametime.
2.1 Modes and implementations of chat logging
There are two modes of chat logging available, strict or relaxed.
Strict logging requires that a message be successfully logged in order to continue the chat session. If an error is encountered, the chat session is terminated.
Relaxed logging records all the messages and a chat continues regardless of whether chat logging succeeds or fails. All servers in a multiple-server environment must be set to run in the same mode.
There are two types of chat logging implementations available for Instant Messaging:
•Synchronous logging:
In synchronous implementations, the message is not sent until it is logged successfully. Chat logging SPI provides sample files for synchronous logging. This type of logging impacts the performance of chat sessions as each chat message must be logged for theconsecutive message.
•Asynchronous logging
Messages are sent regardless of whether they are logged or not.
The chat logging mechanism in
n-way chats and meetings is independent of the type of the chat logging DLL or service program implementation. In
n-way chats and meetings, a chat message string is logged at the same time at which it is forwarded to the recipient.
3 Enabling chat logging
The steps to enable chat logging on the Sametime server are as follows:
1.Stop the Sametime server and use a Lotus Notes® client to open the Sametime Configuration database (STconfig.nsf) on the Sametime server.
2.In the right-hand pane, open the Community Services document by double-clicking on the date associated with the document.
3.Double-click on the Community Services document to put the document in edit mode.
4.For the Chat Logging Flag parameter, select either relax or strict for the chat logging mode. (“Strict" indicates that a chat should be disallowed if it is not possible to log chats for any reason.)
6.Update the Capture Service Type parameter:
•If you selected "strict" as the chat logging mode, enter the value "0x1000" (for example, Capture Service Type = 0x1000).
•If you selected "relax" mode, enter Capture Service Type = 0.
NOTE: If the chat logging service becomes unavailable for any reason when "ChatLogging Flag" is set to "strict" and "Capture Service Type" is set to "0x1000" in the Community Services document, users will receive "Chat services unavailable" when attempting to chat. This is by design; the strict setting is being enforced.
7.Save and close the Community Services document. To finish enabling chat logging, follow the steps below for your server platform.
Microsoft® Windows®
After completing steps 1 through 7 above, complete the steps below to enable chat logging for Windows Sametime servers.
NOTE: To enable chat logging, a chat logging DLL called STChatLog.dll must reside in C:\Lotus\Domino. The chat logging code provided with Sametime (STChatLogFile.dll) isintended as sample code only, as "proof of concept" to demonstrate how the Lotus Sametime SDK can be used to log chats between users.
This sample chat logging DLL can be used as-is but is not supported. For deploymentpurposes, users can develop their own logging application, using the Sametime SDK, or use a third-party application.
1.If STChatLog.dll already exists in the Domino program directory (typically C:\Lotus\Domino), rename STChatLog.dll to STChatLogDummy.dll.
2.To use the sample chat logging DLL to log chats to a text file, rename the fileSTChatLogFile.dll (located in C:\Sametime\DatabaseBB\File) to STChatLog.dll and copy the file to C:\Lotus\Domino.
NOTE: For Sametime versions 6.5.1, 7.5, and 8.0.2, the STChatLog.dll must be obtained from the Directory and Database Access Toolkit, which can be downloaded from the Passport Advantage Web site.
3.Determine where the chat log files should be stored. By default, Sametime will attempt to store them in C:\Lotus\Domino\CLData. If you choose to use this default directory, you must create the "CLData" directory manually, otherwise, the log files will not begenerated.
4.To specify a different directory for storing the chat log files, add the BB_CL_LIBRARY_PATH= parameter to the [Library] section of the Sametime server's Sametime.ini file:
[Library]BB_CL_LIBRARY_PATH=<
full_path_name_of_new_directory
For example, if the Domino server is configured to use "C:\Notes\Data" for its data directory and you have created a subdirectory called "ChatLogs" for logging Sametime chats, the required entry would be:
[Library] BB_CL_LIBRARY_PATH=C:/Notes/Data/ChatLogs
Note that, even though the backward slash character ("\") is the correct directory separator for the Windows operating system, Sametime is expecting a forward slash character ("/"), and the logging will only work when the path is specified this way.
Also, the specified directory must already exist; it will not be created automatically.
5.Restart the Sametime server.
AIX®, Linux®, Solaris®
After completing Steps 1 through 7 (at the beginning of this section), complete these steps to enable chat logging for AIX, Linux, or Solaris Sametime servers:
1.First, determine where the chat log files should be stored. By default, Sametime will attempt to store the chat log files in /Domino/Lotus/Data/CLData. The CLData directory is not created automatically. If you choose to use this default directory, you must create the"CLData" directory manually; otherwise, the log files will not be generated. Ensure that user "notes" and group "notes" have write permission to the new directory.
2.To specify a different directory for storing the chat log files, add the BB_CL_LIBRARY_PATH= parameter to the [Library] section of the Sametime server's sametime.ini file:
[Library] BB_CL_LIBRARY_PATH=<
full_path_name_of_new_directory
For example, if the Sametime server data directory is called /Domino/Lotus/Data and you have created a subdirectory called "ChatLogs" for logging Sametime chats, the required entry would be:
[Library] BB_CL_LIBRARY_PATH=/Domino/Lotus/Data/ChatLogs
This directory must already exist; it will not be created automatically. Also, user "notes" and group "notes" must have write permission to the directory.
3.Restart the Sametime server so that the new setting in STConfig.nsf will take effect.
When testing chat services, you need to chat with a user other than yourself. Chatting with yourself does not open a server channel, so no chat log file is created.
Sametime 8.5 enhancements:
Sametime 8.5 includes new enhancements over previous versions for enabling chat logging. A new file called "chatlogging.ini" could be created in the Domino root folder along with new parameters for customizing chat logging as given below.
1. Use a text editor to edit the sametime.ini file, which is located in the Lotus Sametime Community Server installation directory (for example: C:\Program Files\lotus\domino).
a. Set ST_CHAT_LOG to file in the sametime.ini file under the ST_BB_NAMES section.
ST_CHAT_LOG=file
b. Create chatlogging.ini in the same folder as sametime.ini.
c. Move all the attributes from sametime.ini related to [ChatLogging] to chatlogging.ini. For example:
Note: If you want to use BB_CL_LIBRARY_PATH to change the default location of where the chat logs are stored, then move the [Library] section from sametime.ini to the chatlogging.ini file.
2. Log in to the Integrated Solutions Console.
3. Click Sametime System Console > Sametime Servers > Sametime Community Servers.
Note: Sametime System Console is the new component in Sametime 8.5 family which is used to deploy and centrally manage Sametime 8.5 products.(
http://www-10.lotus.com/ldd/stwiki.nsf/dx/Lotus_Sametime_8.5_Using_the_new_Sametime_System_Console)
4. In the Sametime Community Servers list, click the deployment name of the server with the connectivity information that you want to change.
5. Click the Community Services tab.
6. In the Server Features section, under Enable chat logging, select one of the following choices:
* Always
* When available
* Never
7. Click OK.
8. Restart the Lotus Sametime Community Server for settings to take effect.
4 Chat logging SPI
In 2001, IBM released the Sametime Chat Recording Service Provider Interface (SPI),allowing developers to create and customize Win32 DLL files to capture transcripts of Sametime chats. With the release of Sametime 3, the SPI was incorporated into the Database and Directory Assistance (DDA) toolkit.
The Sametime DDA toolkit documentation provides a detailed description of sample code with functions. The DDA toolkit is one of the toolkits included in Sametime 8.0.1/8.0.2/8.5 SDK. The STChatLogFile.dll provided in Sametime 3.0, 3.1, 6.5.1, 7.0, 8.0.1, 8.0.2 and 8.5 is a sample DLL provided in the Sametime chat logging SPI Toolkit.
The Sametime Chat Logging SPI is a new server-side Sametime feature. This feature can intercept all chat conversations at the server and store a record of them in a data store for future retrieval and reference. The intercepted conversation includes both text and data messages.
The feature is provided as an incentive for developers to create their own DLL (Windows) or shared library (AIX, Linux and Solaris) for storing chats. The DLL or shared library you create implements a predefined SPI used by the server. As the developer, it is your responsibility to store the chats in a data store of your choice so you can retrieve and display them later.
The chat logging SPI sample is an example of the chat logging implementation and can be used as a template for building your customized chat logging DLL or shared library (.so).The SPI provides chat content monitoring, and it can pass back information about the content changes forced in the message.
The SPI allows the chat logging library to block messages or block chat initialization. The decision to block the chat can be based on the chat content or list of chat participants. The chat logging library can return a special Error Code, indicating that the original message should be filtered out or changed, and a new message (or several messages) sent instead.
The chat logging SPI is part of the DDA toolkit that is included in the Sametime 8.0.1/8.0.2/8.5 SDK.
(Download the “IBM Lotus Sametime 8.5 Software Development Kit (SDK) for Multiplatform-CZA6NEN.zip (32 MB)” from the Web site, “
Released product download: Lotus Sametime 8.5
.”
You can extract the files for this toolkit either on your local machine or---to make it available to other users---on your Sametime server. To access the toolkit pages that include the toolkit documentation, samples, and binaries, open the Readme.html in the toolkit root folder.
4.1 Chat logging SPI contents
The contents of the DDA toolkit relevant to the chat logging SPI are:
Sametime DDA SPI documentation
Chat logging SPI sample. This sample provides a file version example of the chat logging SPI implementation and includes examples of constants, error messages,and Sametime.ini configuration. In the file version, each chat is logged in a separate text file, located under a folder defined in the Sametime.ini file. If screen shots were sent during the chat, each screen shot is saved to a separate file.
Chat Logging SPI template. This template or “dummy” version of the chat logging SPI does not return error messages (all return codes are OK) and does not log chat transcripts. Use this template version for building a new chat logging SPI implementation.
Chat Logging SPI header files. These files contain SPI definitions, syntax,variables, constants, return values, and so forth.
5 Considerations and limitations
Note the following points when planning a chat logging implementation.
When using chat logging in a distributed community, all servers must run the same way; either all have chat logging turned on or all have chat logging turned off.
All servers must run in the same mode, either relaxed or strict. If all the servers are not running in the same mode, some chats will be logged and others will not. The logging occurs arbitrarily in this situation.
Chats are logged on the home server of the chat’s recipient in the case of instant messaging.
Synchronous implementation of the chat logging SPI affects the speed of chats in instant messaging. It does not affect the speed of chats in Places.
When using chat logging in a hosted environment in which multiple organizations use a single Sametime server, the stDdaClSessionStartedByOrgName function allows the SPI developer to perform certain preparations for new session logging. This function was added in Sametime 2.6 and is not required to be implemented in non-hosted environments.
Although the Sametime Connect client allows users to chat with AOL Instant Messenger users(AIM), you cannot build a chat logger to capture these chats with the Chat Logging SPI. This is due to the fact that the service is server-based, and AIM chats are client-based.
6 Building and installing a chat logging DLL
Follow these general steps to build and install a chat logging DLL for Windows:
1.Study the provided sample, StChatLogFile.dll, in the toolkit samples\chatloggingdirectory.
2.Use the template version in the toolkit samples\chatlogging directory to create a new Chat Logging SPI implementation. NOTE: When you build your chat logging DLL,leave the sample unchanged.
3.When you create a new DLL, use the debug mechanisms and make sure debug messages are being saved in the trace files, to facilitate troubleshooting during the development and use of the DLL.
4.Save the new DLL under the name StChatLogFile.dll.
5.Test the created DLL. Do not install a new chat logging DLL until you have tested it thoroughly; DLLs directly affect the operation of server components.
6.Replace the dummy chat logging DLL on the Sametime server with the newly created StChatLogFile.dll. The new DLL must be placed in the default directory that contains all other DLLs. The default directory is C:\Program Files\IBM\Lotus\Domino. If more than one server is included in the community, replace the DLL for each server.
7.Make the necessary changes in the STconfig.nsf file of each Sametime server in the community.
8.To activate the new chat logging DLL you created, start and stop the Sametime server on which the DLL is installed. If the Sametime community contains more than one Sametime server, start and stop all servers in the community.
6.1 Building and installing a chat-logging shared library for Linux
Linux applications are implemented through a shared library (.so), as follows:
1. Use the “make” command as follows, to build it:
- cd /tmp/st802sdk/server/dda/samples/chatlogging
- make clean all
The “make” command looks for a file named “makefile” in the current directory (../st802sdk/server/dda/samples/chatlogging) and produces thelibstchatloggingfile.so file. The “clean all” option removes any stale object files.
2.Study the library file, libstchatloggingfile.so.
3.When creating a new .so, use the debug mechanisms and make sure debug messages are being saved in the trace files, to facilitate troubleshooting during the development and use of the so.
4.Test the created .so. Do not install a new chat logging .so until you have tested it thoroughly; .so's directly affect server components' operation.
5.Replace the dummy chat logging .so on the Sametime server with the newly created .so (libstchatloggingfile.so). The new .so must be placed in the default directory that contains all other .so's. The default directory is /opt/ibm/lotus/notes/latest/linux. If more than one server is included in the community, replace the .so for each server.
6.Make sure that the owner and the group for the newly copied .so are both “notes”. If they are not, log in as root and run the following commands:
chown notes libstchatloggingfile.so
chgrp notes libstchatloggingfile.so
7.Similarly, check the permissions for the .so. It should –rwxrwxr-x. If not set properly, change the permissions as follows:
chmod 775 libstchatlogging.so
8.Make the necessary changes in the STconfig.nsf file of each Sametime server in the community.
9.To activate the newly created libstchatloggingfile.so, start and stop the Sametime server on which the .so is installed. If the Sametime community contains more than one Sametime server, start and stop all the servers in the community.
6.2 Tips for proper SPI operation
Follow these standards to ensure proper operation of the chat logging SPI:
The value of the libversion parameter is saved in the Sametime log file(sametime.log). Every time the chat logging SPI version is changed, its number is incremented, and the information in the Sametime log file is updated accordingly. Use this parameter to keep track of the used versions.
The stDdaClInit function initializes the chat logging library and verifies that it canhandle the specified version of the SPI. The calling application places the SPI version number in the prVersion parameter. The chat logging library adjusts its SPI version number to the version of calling application. If the version numbers are equal, the initialization continues.
If the SPI version number of the chat logging library is higher than the SPI version number of the calling application, the chat logging SPI decides whether it can work with a lower-version SPI. Depending on the particular configuration, the initialization either continues, or an error message is returned.
If the SPI version number of the chat logging directory is lower than the SPI version number of the calling application, the calling application decides whether it can work with a lower-version SPI. Depending on the particular configuration, the initialization either continues, or an error message is returned.
•The retcode and retmsg parameters provide information about the application status. Retcode is returned from each function, and a retmsg matches the specific retcode. The value of retmsg is saved in the log or trace files. Use this standard to continue receiving updates on the status of the application.
Logging and retrieving chat transcripts
The chat transcripts can be stored in a database, in a file, or in a set of files. It is best to run a global directory of all logged chats or log chat transcripts in one database, which is replicated by the servers. It is possible to develop a mechanism for filtering the messages and chat transcripts so that only predefined chats are logged.
7 Chat logging SPI sample
The chat logging SPI sample provides an example of synchronous implementation of the chat logging SPI feature. It can be found on the DDA SPI toolkit home page. In the chat logging SPI sample, each chat transcript is logged in a separate text file under a folder defined in the Sametime.ini file.
If screen shots are sent during the chat, each screen shot picture is saved into a separate file in the same folder. The file version provides examples of constants, error messages, and additional Sametime.ini flags. The chat logging sample included in Sametime 8.5 SDK is enhanced and offers rich text support and images/emoticon support
7.1 Sametime.ini flags for the SPI sample
The following Sametime.ini flags have been specially created for the chat logging SPI sample:
BB_CL_TRACE flag. Used for recording the chat logging SPI sample debug messages in trace files. To enable the recording, set BB_CL_TRACE to 1.
BB_CL_LIBRARY_PATH flag (in the [Library] section). Used to specify the location for logging chat transcripts. In this sample, chat transcripts are saved in thesametime\CLData folder.
CL_BAN_CHAT_BETWEEN_USERS. Used to set two names of users, to imitate session initialization forbidding. Examples:
CL_BAN_CHAT_BETWEEN_USERS=CN=John Smith/O=Ubique,CN=PeterPan/O=Ubique
For an LDAP configuration:
CN_BAN_CHAT_BETWEEN_USERS="uid=JohnSmith,ou=sametime,dc=ibm,dc=com","uid=TomPeters,ou=sametime,dc=ibm,dc=com".
In case the names contain commas, you can bound the names by quotes; forexample:
CL_BAN_CHAT_BETWEEN_USERS="CN=John Smith,O=Ubique","CN=PeterPan,O=Ubique"
•
CL_BAN_CHAT_WARNING_MSG. Used to supply a message that is sent to the client when a session initialization attempt is forbidden. For example:
CL_BAN_CHAT_WARNING_MSG=Chat initialization was banned by Chat Logging
CL_REPLACE_STRINGS_IN_MSG. Used to set two strings, when the first string isa pattern to be searched and replaced by the second string. For example:
CL_REPLACE_STRINGS_IN_MSG=June,July
If the strings contain commas, you can bound the strings by quotes. For example:
CL_REPLACE_STRINGS_IN_MSG="June, June","July,July"
CL_DELETE_MSG_WITH_STRING. Used to set a sub string, that when found in a message, the message will be deleted. For example:
CL_DELETE_MSG_WITH_STRING=August
•
CL_WARNING_ON_DELETED_MSG. Used to set a warning message, which will be sent when the original message is deleted. For example:
CL_WARNING_ON_DELETED_MSG=The last message was deleted by Chat Logging
8 Chat logging SPI sample parameters
Table 1 shows the error messages that were developed specifically for the chat logging SPI sample.
Table 1. Chat logging SPI error messages
|
|
|
|
ST_DDA_CL_SESSION_ALREADY_EXISTS
|
|
The operation could not be performed because the specified session ID is already in use.
|
ST_DDA_CL_SESSION_DOES_NOT_EXIST
|
|
The indicated session ID does not exist.
|
|
|
|
Access to the data store was denied.
|
ST_DDA_SESSION_CREATION_DECLINED
|
|
The chat session initialization is declined by the Chat Logging.
|
ST_DDA_SESSION_CLOSED_BY_SERVER
|
|
The chat session is closed by the Chat Logging.
|
|
|
|
The original message was changed or replaced by the Chat Logging.
|
Table 2 shows the chat logging SPI sample constants.
Table 2. Chat logging SPI sample constants
|
|
|
|
|
|
|
The maximum length of the message string that can be logged.
|
|
|
|
The maximum length of the login name, user name and group name.
|
|
|
|
The maximum length of the string.
|
|
|
|
The maximum message size of a path or a file name.
|
|
|
|
The file type of the files where chat transcripts are saved.
|
|
|
|
The section of a sametime.ini file where the DEFAULT_LIB_PATH flag is written.
|
|
|
|
The default location of the folder where the chat transcripts are saved.
|
|
|
|
The name of the debug flag in the sametime.ini file. This flag determines the folder where chat transcripts are saved.
|
|
|
|
The name of the Chat Logging SPI configuration file.
|
|
|
|
The name and location of the trace files where the debug messages are recorded.
|
Message Value Description CL_PREFIX_NAME
|
|
The prefix for the name of the trace file
|
8.1 Chat logging SPI sample code
The stDdaClApi.cpp file implements the chat logging SPI by using the ChatSessionTable.h, ChatSessionTable.cpp, ChatResource.h, and ChatResource.cpp files.
The ChatResource class is responsible for:
• Getting all the .ini flags from the Sametime.ini
• Creating the default path for session files
• Printing debug messages to the trace file
• Getting the current time string
• Determining whether the data message contains an image
Table 3 lists and describes the return messages common to all Sametime Toolkit SPIs,APIs, and DLLs, including the chat logging SPI.
Table 3. Chat logging SPI return messages
|
|
|
|
|
|
|
Returned by the SPI functions when the requested operation succeeds
|
ST_DDA_API_VERSION_MISMATCH
|
|
Returned by the initialization function if version incompatibility is found
|
|
|
|
Returned by the SPI functions when an operation cannot be performed because one or more of the parameters does not match the specifications (for example, wrong length of user name, wrong format of token, etc.)
|
ST_DDA_API_INTERNAL_ERROR
|
|
Returned by the SPI functions when an operation fails due to a problem other than those in this table
|
|
|
|
Returned by the initialization function if the chat logging library does not support the SPI version
|
Table 4 lists and describes the constants defined in stDdaApiDefs.h that are common to all Sametime toolkit SPIs and APIs, including the chat logging SPI.
Table 4. Chat logging SPI constants
|
|
|
|
|
|
|
The maximum length of the login name, user name, and group name.
|
|
|
|
The maximum length of a user ID or group ID.
|
ST_DDA_MAX_DESCRIPTION_LENGTH
|
|
The maximum length of a user description or a group description string.
|
ST_DDA_API_NOTES, ST_DDA_API_LDAP, ST_DDA_API_DB2
|
0x0002, 0x0004, 0x0008, respectively
|
Indicate which platform interfaces were initialized. No other types of platform interfaces are specified. If the platform interface in use is not defined, use a higher bit (for example, 0x08 or 0x10).
|
8.2 Chat logging SPI functions
The Sametime chat logging SPI provides the following functions:
stDdaClInit – Initializes chat logging library
stDdaClTerminate – Terminates any platform interface initialized by the library
stDdaClTimerEvent – Performs time-based actions such as refreshing a cache or reconnecting to the database
stDdaClSessionStarted – Performs certain preparations for new session logging
stDdaClSessionStartedByOrgName – Performs similar to “stDdaClSessionStarted”and is used specifically in hosted environments in which multiple organizations use a single Sametime server.
stDdaClSessionEnded – Takes care of ending sessions
stDdaClEntity – Describes a participant in a chat session
stClEntityType – This enumerator defines the different types of participants
stDdaClJoiningSession – Identifies the scope that each new participant is joining
stDdaClSessionPolicycheckFunc – Enforces banning in one-on-one chat
stDdaClLeavingSession – Identifies the participant who is leaving a session
stDdaClSessionMsg – Identifies the source destination and content of the message
stDdaClSessionDataMsg – Identifies the source destination and content of the data message
stDdaClJoiningSessionWithSrvMsg – Identifies the scope that each new participant is joining
stDdaClLeavingSessionWithSrvMsg – Identifies the participant who is leaving a session
stDdaClSessionMsgWithSrvMsg – Identifies the source destination and content of the message
stDdaClSessionDataMsgWithSrvMsg – Identifies the source destination and content of the data message
stDdaClCleanSrvMsgs – Deletes the server messages and frees the allocated memory
9 Error handling
The chat logging SPI can pass back information about its status in the form of a code and a message. Two variables are defined globally inside the calling application:
•
stDdaRetVal – An enumerator for the return state of the most recent SPI call.
•
stDdaRetStr – A character buffer for a string with a textual explanation of the return code.
The pointers to these variables are passed by the application to the chat logging SPI in the initialization call. Table 5 defines the possible values for the stDdaRetVal enumerator.
Table 5. Possible values for stDdaRetVal
|
|
|
|
|
The operation was completed successfully.
|
|
|
The operation was completed successfully, but there is an informative message.
|
|
|
The operation was completed, but a warning was issued.
|
|
|
|
|
|
The operation failed and the application should stop calling the specific SPI.
|
ST_DDA_SESSION_CREATION_DECLINED
|
The chat session initialization was declined by the Chat Logging library.
|
ST_DDA_SESSION_CLOSED_BY_SERVER
|
The chat session was closed by the Chat Logging library.
|
|
|
The chat logging changed the original message. The new messages should be sent instead of the original message.
|
9.1 Preventing chats between two users using the SPI function
By using “stDdaClCleanSrvMsgs” and “stDdaClSessionPolicycheckFunc” functions, we can forbid a chat between two users in a one-on-one chat. This function does not work for
n-way chats; instead, use stDdaClJoiningSession or stDdaClJoiningSessionWithSrvMsg.
The code is as follows:
stDdaClSessionPolicycheckFunc(/*in*/ const StDdaClEntity* entity,
/*in*/ const StDdaClEntity* toEntity,
/*out*/ StDdaClSrvMsg
srvMessages,
/*out*/ unsigned long* srvMessagesLen)
{
CHAT_RSC.print(dbg,"stDdaClSessionPolicycheckFunc: processing...");
string from_user;
string to_user;
from_user = entity->id;
to_user = toEntity->id;
if(CHAT_RSC.isAttempToBanChats()) {
if((from_user CHAT_RSC.getBanChatFrom() && to_user
CHAT_RSC.getBanChatTo()) ||
(to_user CHAT_RSC.getBanChatFrom() && from_user
CHAT_RSC.getBanChatTo())) {
the chat should be banned
CHAT_RSC.print(dbg,"It is forbidden to open chat between %s and %s", from_user.c_str(),to_user.c_str());
if(strlen(CHAT_RSC.getBanChatWarning()) > 0) {
- srvMessagesLen = (unsigned long)1;
- srvMessages = new StDdaClSrvMsg();
(*srvMessages)->srvMsgType = ST_DDA_CL_TEXT_MSG;
(*srvMessages)->srvMsgDestination = ST_DDA_CL_SENDER;
int msgLen = strlen(CHAT_RSC.getBanChatWarning());
char* buf = new char[msgLen + 1];
memset(buf, 0, msgLen + 1);
strncpy(buf, CHAT_RSC.getBanChatWarning(), msgLen);
(*srvMessages)->msg = buf;
}
return ST_DDA_SESSION_CREATION_DECLINED;
}
}
CHAT_RSC.print(dbg,"stDdaClSessionPolicycheckFunc: ended ok");
return ST_DDA_OK;
}
10 Conclusion
You should now have a good understanding of the basics of Sametime chat logging, chat logging types, and the main features, implementations, and limitations. We also provided an in-depth discussion of the Sametime chat logging SPI, detailing its functions and parameters. For customizing real-time environments, a custom chat logging dll (Windows)or .so (Linux) file is required, and we presented the steps to build this custom file.
11 Resources
Lotus Sametime developerWorks product page:
http://www.ibm.com/developerworks/lotus/products/instantmessaging/?S_TACT=105AGX13&S_CMP=LP
IBM Redbooks publication: “Lotus Instant Messaging/Web Conferencing (Sametime): BuildingSametime Enabled applications”:
http://www.redbooks.ibm.com/abstracts/sg247037.html
Sametime 8.0.2 SDK download:
http://www14.software.ibm.com/webapp/download/preconfig.jsp?id=2008-08-04+09%3A36%3A57.015169R&S_TACT=104CBW71&S_CMP=
Lotus Support Technote #1086729, “How to enable chat logging on a Sametime server”:
http://www-01.ibm.com/support/docview.wss?rs=477&uid=swg21086729
About the author
Anbuchezhian Balakrishnan is a Software Engineer based at IBM's Dublin Software Labs,currently working on Sametime System Verification Testing projects. His areas of expertise include IBM Tivoli® Systems Management solutions, Tivoli Security Management Solutions,Tivoli software testing, Sametime Enterprise Meeting server implementations, and Sametime 8.0.2 and 8.5.x products testing.