Same Time Dat K Daev Guide

Lotus Instant Messaging and Web Conferencing
Directory and Database Access Toolkit
Version 6.5.1
Developers Guide
G210-1728-00
Copyright and Trademark Information

Disclaimer
THE INFORMATION CONTAINED IN THIS DOCUMENTATION IS PROVIDED FOR INFORMATIONAL PURPOSES ONLY. WHILE EFFORTS WERE MADE TO VERIFY THE COMPLETENESS AND ACCURACY OF THE INFORMATION CONTAINED IN THIS DOCUMENTATION, IT IS PROVIDED AS IS WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. IN ADDITION, THIS INFORMATION IS BASED ON IBMS CURRENT PRODUCT PLANS AND STRATEGY, WHICH ARE SUBJECT TO CHANGE BY IBM WITHOUT NOTICE. IBM SHALL NOT BE RESPONSIBLE FOR ANY DAMAGES ARISING OUT OF THE USE OF, OR OTHERWISE RELATED TO, THIS DOCUMENTATION OR ANY OTHER DOCUMENTATION. NOTHING CONTAINED IN THIS DOCUMENTATION IS INTENDED TO, NOR SHALL HAVE THE EFFECT OF, CREATING ANY WARRANTIES OR REPRESENTATIONS FROM IBM (OR ITS SUPPLIERS OR LICENSORS), OR ALTERING THE TERMS AND CONDITIONS OF THE APPLICABLE LICENSE AGREEMENT GOVERNING THE USE OF IBM SOFTWARE.
Licensed Materials - Property of IBM

Copyright IBM Corporation 2002, 2004 All rights reserved. US Government Users Restricted Rights - Use, duplication or disclosure restricted by GS ADP Schedule Contract with IBM Corp.
Lotus Software IBM Software Group One Rogers Street Cambridge, MA 02142
List of Trademarks
IBM, the IBM logo, 1-2-3, AIX, AS/400, DB2, Domino, Domino Designer, iNotes, iSeries, Lotus, Lotus Notes, MQSeries, Netfinity, Notes, QuickPlace, Sametime, SmartSuite, S/390, Tivoli, WebSphere, and Word Pro are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries, or both. Pentium is a trademark of Intel Corporation in the United States, other countries, or both. Microsoft, Windows, and Windows NT are registered trademarks of Microsoft Corporation in the United States, other countries, or both. UNIX is a registered trademark of The Open Group in the United States and other countries. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. Other company, product, or service names may be trademarks or service marks of others.
Third Party Notices For the XSL and XML Parser and Processor
The Apache Software License, Version 1.1 Copyright (c) 1999-2000 The Apache Software Foundation. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. The end-user documentation included with the redistribution, if any, must include the following acknowledgment: "This product includes software developed by the Apache Software Foundation (http://www.apache.org/)." Alternately, this acknowledgment may appear in the software itself, if and wherever such third-party acknowledgments normally appear. 4. The names "Xerces" and "Apache Software Foundation" must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact apache@apache.org. 5. Products derived from this software may not be called "Apache," nor may "Apache" appear in their name, without prior written permission of the Apache Software Foundation.
THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. This software consists of voluntary contributions made by many individuals on behalf of the Apache Software Foundation and was originally based on software copyright (c) 1999, International Business Machines, Inc., http://www.ibm.com. For more information on the Apache Software Foundation, please see http://www.apache.org/.
For DSIG base64

COPYRIGHT 1995 BY: MASSACHUSETTS INSTITUTE OF TECHNOLOGY (MIT), INRIA This W3C software is being provided by the copyright holders under the following license. By obtaining, using and/or copying this software, you agree that you have read, understood, and will comply with the following terms and conditions: Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee or royalty is hereby granted, provided that the full text of this NOTICE appears on ALL copies of the software and documentation or portions thereof, including modifications, that you make. THIS SOFTWARE IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION,
COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS. COPYRIGHT HOLDERS WILL BEAR NO LIABILITY FOR ANY USE OF THIS SOFTWARE OR DOCUMENTATION. The name and trademarks of copyright holders may NOT be used in advertising or publicity pertaining to the software without specific, written prior permission. Title to copyright in this software and any associated documentation will at all times remain with copyright holders.
For STLport
License Agreement Boris Fomitchev grants Licensee a non-exclusive, non-transferable, royalty-free license to use STLport and its documentation without fee. By downloading, using, or copying STLport or any portion thereof, Licensee agrees to abide by the intellectual property laws and all other applicable laws of the United States of America, and to all of the terms and conditions of this Agreement. Licensee shall maintain the following copyright and permissionnotices on STLport sources and its documentation unchanged : Copyright 1999,2000 Boris Fomitchev This material is provided "as is", with absolutely no warranty expressed or implied. Any use is at your own risk. Permission to use or copy this software for any purpose is hereby granted without fee, provided the above notices are retained on all copies. Permission to modify the code and to distribute modified code is granted, provided the above notices are retained, and a notice that the code was modified is included with the above copyright notice. The Licensee may distribute binaries compiled with STLport (whether original or modified) without any royalties or restrictions. The Licensee may distribute original or modified STLport sources, provided that: The conditions indicated in the above permission notice are met; The following copyright notices are retained when present, and conditions provided in accompanying permission notices are met : Copyright 1994 Hewlett-Packard Company Copyright 1996,97 Silicon Graphics Computer Systems, Inc. Copyright 1997 Moscow Center for SPARC Technology. Permission to use, copy, modify, distribute and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. Hewlett-Packard Company makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty. Permission to use, copy, modify, distribute and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. Silicon Graphics makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty. Permission to use, copy, modify, distribute and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. Moscow Center for SPARC Technology makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty. Copyright 2001 by STLport
For MD5 hash

Copyright (C) 1990, RSA Data Security, Inc. All rights reserved. License to copy and use this software is granted provided that it is identified as the "RSA Data Security, Inc. MD5 Message-Digest Algorithm" in all material mentioning or referencing this software or this function. License is also granted to make and use derivative works provided that such works are identified as "derived from the RSA Data Security, Inc. MD5 Message-Digest Algorithm" in all material mentioning or referencing the derived work. RSA Data Security, Inc. makes no representations concerning either the merchantability of this software or the suitability of this software for any particular purpose. It is provided "as is" without express or implied warranty of any kind. These notices must be retained in any copies of any part of this documentation and/or software.
For Log4J Logging

The Apache Software License, Version 1.1 at http://www.apache.org/LICENSE, 24 May 2002 The Apache Software License, Version 1.1 Copyright (c) 2000 The Apache Software Foundation. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
6. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 7. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 8. The end-user documentation included with the redistribution, if any, must include the following acknowledgment: "This product includes software developed by the Apache Software Foundation (http://www.apache.org/)." Alternately, this acknowledgment may appear in the software itself, if and wherever such third-party acknowledgments normally appear. 9. The names "Apache" and "Apache Software Foundation" must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact apache@apache.org. 10. Products derived from this software may not be called "Apache", nor may "Apache" appear in their name, without prior written permission of the Apache Software Foundation.
THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. This software consists of voluntary contributions made by many individuals on behalf of the Apache Software Foundation. For more information on the Apache Software Foundation, please see <http://www.apache.org/>. Portions of this software are based upon public domain software originally written at the National Center for Supercomputing Applications, University of Illinois, Urbana-Champaign.
Table of Contents
About This Guide ............................................................................................................1
Chapter 1 Introduction..............................................................................................4
Persistent Data in the Community Server......................................................... 4

Chapter 2 Chat Logging SPI.....................................................................................7
Introduction to the Chat Logging SPI................................................................ 7
Architecture................................................................................................................7 Chat Logging Management.......................................................................................8
Getting Started .................................................................................................. 13
Chat Logging SPI Contents ................................................................................... 13

Building the Chat Logging DLL or Service Program .......................................... 13
Chat Logging SPI Sample................................................................................. 19
Sametime.ini Flags for the Chat Logging SPI Sample ........................................ 19

Chat Logging SPI Sample Parameters ................................................................. 19
Chat Logging SPI Sample Code ............................................................................ 22
Chat Logging SPI Reference ............................................................................ 43
Chat Logging SPI Parameters ............................................................................... 43

Chat Logging SPI Functions.................................................................................. 45
Common Structures ............................................................................................... 52
Chapter 3
Token Authentication SPI .....................................................................57
Introduction ....................................................................................................... 57
Getting Started .................................................................................................. 57
Token Authentication SPI Contents...................................................................... 58
Building the Token Authentication DLL or Service Program........................ 58
Instant Messaging and Web Conferencing Directory and Database Access Toolkit Developers Guide
Table of Contents
Token Authentication SPI Reference .............................................................. 63
Token Authentication SPI Parameters ................................................................. 63

Token Authentication SPI Functions .................................................................... 65
ii
About This Guide

Intended Audience
The guide explains the IBM Lotus Instant Messaging and Web Conferencing (Lotus Sametime) Directory and Database Access Service Provider Interface (SPI). It is intended for developers deploying Sametime who want to customize the access level to the organization directory and/or database.
Note
Throughout this guide, the IBM Lotus Instant Messaging and Web Conferencing product is referred to as Sametime, and this and other toolkits are referred to as Sametime toolkits.
Requirements
The Directory and Database Access Toolkit is implemented as a DLL for the Windows operating system supported by the server and as a service program for IBM iSeriesTM. This documentation is intended primarily for Windows developers; the Chat Logging SPI template and the Token Authentication SPI template are currently implemented only for the Windows operating system with the Microsoft C Development environment. However, iSeries developers can use the same source files in adapting the samples for use in these environments. The toolkit is targeted for use with the following Sametime servers: Windows 2.5 and above. iSeries 3.1 and above
Although applications developed with this toolkit will work when run on a Sametime 2.x or later server, toolkit services that require features new to this release will not function. In particular, the code examples in the toolkit should be run on the latest version of the Sametime server.
About This Guide
How to Use this Guide

This guide contains the following main sections. Chapter title Chapter 1: Introduction Description Provides an overview of the logic and access layers. Provides an explanation of the Chat Logging SPI and its management. Includes function reference guide. Describes the Token Authentication SPI. Includes function reference guide.
Chapter 2: Chat Logging SPI
Chapter 3: Token Authentication SPI
Toolkit Contents
Documentation Sametime Directory and Database Access Toolkit Developers Guide (this document) Chat Logging SPI sample Chat Logging SPI template Chat Logging SPI header files Token Authentication SPI template Token Authentication SPI header files
Related Documents
Sametime Installation Guide Sametime Administrators Guide
Additional Information
See these Web sites for more information: http://www.lotus.com/sametime http://www.ibm.com/developerworks/lotus
About This Guide
You may also want to read Working with the Sametime Client Toolkits, available at the IBM Redbooks site (http://www.redbooks.ibm.com).
Chapter 1 Introduction
Persistent Data in the Community Server
The Community server, as part of the Sametime server, provides services for awareness, chat, and meeting places. It uses persistent data storage to save and retrieve persistent information in the implementation of these services. This information can be divided into these different types: Directory information Sametime requires access to an organization directory in order to identify different users, authenticate users, allow users to search in the directory, and perform other such actions. This directory might already exist and might be in use by other applications. Sametime requires read access only to this directory. User information Information about users that is specific to Sametime, written and used by Sametime. Administration information Information specific to Sametime about the community server(s) in the organization. This information includes configuration details, log information, and other information that is used by the servers or is needed by Sametime administrators. Access to the databases where this information is stored is implemented through these layers: The logical layer Implements the logic of accessing the databases without any dependency on the type of database that is used. The access layer Implements the access to a specific database. The logic layer is implemented once. The access layer is implemented separately for each database type. Sametime includes an implementation of this layer. Sametime also publishes the definition of the Chat Logging and Token Authentication SPIs so that customers can adopt them to their environments.
Directory Access
The directory stores the organizations user information. You can deploy Sametime so it uses your existing organization directory or so it creates and uses its own built-in directory. If you already have a directory in the organization, it is assumed that you want to use that directory.
You can use an existing directory in one of these ways: Using the out of the box access layer supplied by the Sametime product - If you have a Notes directory (NAB) or an LDAP directory, Sametime provides an access layer that functions with these directory types. If you are using an LDAP directory, you might need to tune the connection but you dont need to customize the access layer. Customizing the access layer - If you are not using a Notes directory or an LDAP directory or if you are using an LDAP directory but would like to implement your own access layer, you can customize the access layer to do so. Sametime servers only read information from the directory; they do not write it. Because they do not make any changes to the directory, you can use your organizations existing directory safely. Sametime uses the directory for these services: Authenticating users Confirms that whoever is trying to log in to the Sametime community is authorized to do so. Searching Allows people to search in the directory for other people or groups in the organization and add them to their contact list. When the end-user types a name or a part of a name, the server searches for matches in the directory. Browsing Allows people to browse the contents of the directory. This is a complimentary service to the search service. Browsing is used when the end-user knows part of the name and would like to find the correct match by browsing the entire directory. Groups Provides the service for retrieving the contents of a public group. In addition to the directory-related services above, there is one other service that is related to the directory information: Token Authentication A component that handles token generation and verification. The Token Authentication SPI is included in this toolkit. Sametime supports two types of authentication tokens out-of-the-box: Proprietary Sametime token LTPA token supported by DominoTM and WebSphere The Token Authentication SPI allows you to customize Sametime for a different kind of token generated in your deployment.
Database Access
The user information database contains Sametime-specific information about users. In addition to the user information in the organization directory, Sametime stores and uses this additional
information about each user. This information is saved on the server to allow the user access to the information from any computer. The user information is stored in a Notes database in a regular deployment or in DB2 database in a Community Stand-Alone deployment; this storage is the out of the box implementation of the access layer. You can customize this implementation for a different database storage system, such as any SQL server. Sametime stores two types of additional user information: Privacy information Stores and retrieves the privacy information of a user. User preferences Stores and restores the preferences of the user: the contact list, messages, alarms, and so on. The only part of the user preference not stored on the server is the connectivity information. The interface between the logical layer and the access layer allows setting and retrieving the above information.
Configuration Data Access

Administration information databases contain information for configuration and logging settings. These databases are used by the administrator to modify the configuration of the community and to monitor the status of the servers. These databases include: Servers configuration Contains information about Sametime servers and their configuration parameters. Use the Sametime administration tool to modify this data. If you change the place you store this information, you must then provide an alternative method for modifying the information. Server log Records events from the server. The set of events is defined in advance. You can choose which one to record and which one not to record. Chat logging Stores the chat transcripts for future reference. Administrators and supervisors can review chats even if they did not participate in the chat. This Chat Logging SPI is included in this toolkit.
Chapter 2 Chat Logging SPI

Introduction to the Chat Logging SPI
The Sametime Chat Logging Server Provider Interface (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 feature is provided as an incentive for developers to create their own DLL (or service program, for IBM iSeries users) for storing chats. The DLL or service program 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 that 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 service program.
Note An instant message (IM) chat between a Sametime user and an AOL user cannot be
logged.
Architecture
Sametime contains two mechanisms for text conversations between users: Instant messaging (IM) N-way chat and meetings
When an entity (a user, server, or a server application) needs to communicate with another entity, it creates a channel to the other entity. The channel can be encrypted if necessary. (For more information on channel encryption, see the Instant messaging and the N-way chat sections that follow.) The recipient can choose to accept or reject the channel.
Instant messaging
Instant messaging allows two people to exchange messages that they type via their computer keyboards. Instant messages are exchanged between two people only. When user A wants to have a chat with user B, user A selects user B, which causes the server to create a channel to user B. If approved, the server connects the two users and thereafter acts only as a router, transferring the messages from one user to the other. In Sametime 3.0 and above, the messages are encrypted by default.
Note Sametime versions 2.0 and prior include an option for non-encrypted chats. If this option
is selected, the encryption default is overridden and the chat is not encrypted. In addition, instant messages that are created using the Chat Logging SPI and sent by clients might not be encrypted.
N-way chat
An n-way chat is the exchange of online messages among more than two users. The messages are encrypted by default. An n-way chat is created when: Two users in an instant meeting (IM) invite an additional user to the conversation. One user invites at least two other users to a chat.
Note
Sametime versions 2.0 and prior include an option for non-encrypted chats. If this option is selected, the encryption default is overridden and the n-way chat is not encrypted. In addition, instant messages that are created using the Chat Logging SPI and sent by clients might not be encrypted.
While instant messages are only one-to-one, n-way chats use a different mechanism called a Place to exchange messages among multiple participants.
Place
A Place is a server-side component where users meet and exchange messages. Users who want to participate in the conversation must enter the Place. Upon joining a Place, the users are put into sections. Each Place has one or more sections, and each section has zero or more users. Having sections enables the client applications to allow the user to send messages to different participants or scopes. (The scope refers to the number of participants who will receive a message.) The types of scopes are: Place scope When a message is sent to the Place scope, all the participants in the Place receive it. Section scope When a message is sent to the section scope, only the participants of the section receive it. Individual scope When a message is sent to a specific participant in a Place, only that individual receives the message. Activities Activities represent server-side components that add value, content, and activity to the place. They are a type of participant in a Place and, as participants, can send messages and receive messages that are sent to them or to the Place scope.
Chat Logging Management

Chat logging management requires that you understand how chat logging works. See the following topics for an understanding of chat logging: Modes Chat logging in a Distributed Environment
Synchronous and Asynchronous Implementation Error Handling Chat Logging Effect on Sametime Server Performance
Modes
The two modes of chat logging are: Strict chat logging If the chat logging service is not present or an error message about the Chat Logging SPI functions is received, all existing chats and chats in Places will be disconnected, and users will not be able to start new chats. Relaxed chat logging As long as the chat logging service is running, chats are logged. Even if errors are received, chats can be created or continue running.
Chat Logging in a Distributed Environment

When using the chat logging feature in a distributed or multi-server environment, an IM or chat in a Place can occur between two users connected to different Sametime servers. A distributed Sametime environment contains more than one Sametime server. Installing multiple Sametime servers provides several advantages related to load balancing and network usage and can enhance meeting and server performance. For more information, see the Sametime Administrators Guide and the Sametime Installation Guide. The chat transcript is logged only once: In an n-way chat or a meeting, the location of the server on which the chat is logged is the server on which the Place is handled. In an instant messaging session, the chat is logged onto the home server of the user that accepted the IM.
Note If user A initiates a chat with user B, the chat is logged in the home server of the chats
recipient user B. If in the course of the chat, user A closes the chat window, but user B continues to write, a new chat session is created in which user B is the initiator and user A is the recipient. From this point on the chat is logged on the home server of user A.
Synchronous and Asynchronous Implementation

A chat logging DLL or service program can be implemented asynchronously (message is sent regardless of its logged state) or synchronously (message is not sent until it is logged successfully). Sametime provides the Chat Logging SPI sample for synchronous implementation. You can develop your own chat logging DLL or service program with asynchronous implementation.
Instant messaging The chat logging mechanism for chats in IMs differs from the chat logging mechanism for chats in n-way chats and meetings. In IMs, each chat message string is logged into the data store before it is forwarded to the recipient. If the chat logging DLL or service program is implemented synchronously, the chat message string is not forwarded to the recipient until this string is successfully logged in the data store. This delay slows down the IM operation. Asynchronous implementation of the chat logging DLL or service program does not affect the IM operation because the chat message string is forwarded to the recipient without waiting for it to be logged to the data store. N-way chats 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 that it is forwarded to the recipient.
Retrieving Chats
The purpose of chat logging is to be able to later search the logged conversations and read them. Sametime does not provide such a tool. You develop the tool that searches the data store and retrieves the logged conversations.
Administration
Use the Sametime STConfig.nsf file to configure chat logging. 1. Create or open the CommunityServices document. 2. Enable chat logging by choosing one of the following values for the Chat Logging Flag field:: Off No chat logging will occur. Relaxed Chat logging will occur; if it does not work for any reason, chat is still enabled. Strict Chat logging will occur; if it does not work for any reason, chat is disabled.
Note
If chat logging is not enabled, the chat logging server application will not function.
3. For the Capture Service Type field, specify 0 for no chat logging or 0x1000 for chat logging. 4. Restart the Sametime Configuration service so that your changes will take effect immediately. In a distributed community, the administrator should configure all the servers at once, and configure them all the same way: either all have chat logging turned on, or all do not. Also, they should all be running in the same mode: either relaxed mode or strict mode. (See the Modes section for more information.)
10
Caution 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.
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. For more information, see the Chat Logging SPI Functions section. The table below defines the possible values for the enumerator stDdaRetVal:
Value ST_DDA_OK ST_DDA_INFO Description
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. The operation failed, and the application should stop calling the specific SPI.
ST_DDA_WARNING ST_DDA_ERROR ST_DDA_FATAL
It is the responsibility of the developer implementing a chat logging DLL or service program to make sure that information is not lost. For example, if an informational message is created and later a fatal error occurs, the informational message might hold data crucial for understanding the cause of the fatal condition but is not saved because of the fatal error. To avoid overwriting of messages and to retain all message information, the messages should be concatenated.
Chat Logging Effect on the Sametime Server Performance

The effect of chat logging on the Sametime server depends on the chat logging operation and implementation modes. See the Modes and Synchronous and Asynchronous Implementation sections of this chapter for more information.
11
Chat logging operation mode In relaxed mode, if the chat logging application does not work, the malfunction has no effect on the Sametime server. Users can create new Places and new IMs and send invitations, and the existing Places and IMs continue to function. In strict mode, if one of the Chat Logging SPI functions returns errors, all existing IMs and chats in Places will be destroyed. Chat logging implementation mode If the Chat Logging SPI is implemented synchronously, the operation of chats in instant messages is slower than usual. The operation of chats in n-way chats and meetings in Places is not affected. If the Chat Logging SPI is implemented asynchronously, the operation of the chats in both instant messages and Places is not affected.
12
Getting Started
The Chat Logging SPI is part of the Directory and Database Access Toolkit. To install the toolkit, visit http://www.ibm.com/developerworks/lotus/products/. On the Products page, click Lotus Instant Messaging and Web Conferencing (Sametime). The Lotus Instant Messaging and Web Conferencing (Sametime) page contains links to all the documentation and downloads. 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 index.html in the toolkit root folder. Assuming that the toolkit is installed in \<server data directory>\domino\html\ST651DDAToolkit, you can access the toolkit home page at http://<server hostname>/ST651DDAToolkit/index.html.
Chat Logging SPI Contents

The contents of the Directory and Databases Access Toolkit that concern the Chat Logging SPI are: Sametime Directory and Database Access SPI documentation This document Chat Logging SPI sample This sample provides a file version example of Chat Logging SPI implementation. It provides examples of constants, error messages, and sametime.ini configuration. In the file version, each chat is logged in a separate text file that is located under a folder defined in the sametime.ini file. For more information on the Chat Logging SPI sample, refer to the Chat Logging SPI Sample section of this document. 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 no chat transcripts are logged. 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 on.
Building the Chat Logging DLL or Service Program

This toolkit does not provide a full version of the chat logging DLL or service program. Use the Chat Logging SPI template and the Chat Logging SPI sample to complete development of the chat logging SPI for your particular environment(s).
13
When creating the chat logging DLL or service program: Follow the interface defined by the Chat Logging SPI. Develop a mechanism for storing the messages and a mechanism for retrieving them at a later date. To ensure proper operation of the chat logging DLL or service program, see the following topics: General considerations Building and Installing a Chat Logging DLL for Windows Building and Installing a Chat Logging Service Program for IBM iSeries Recommendations
General Considerations
These chat logging features must be considered when planning the 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.
Caution 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. With an instant message, a chat is logged on the home server of the chats recipient. 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. For more information about the synchronous and asynchronous implementation of the Chat Logging SPI, see the Synchronous and Asynchronous Implementation section of this chapter. When using chat logging in a hosted environment where 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. See the stDdaClSessionStartedByOrgName function for more information.
Building and Installing a Chat Logging DLL for Windows

Follow these general steps for building and installing a chat logging DLL: 5. Study the provided sample, StChatLogFile.dll in the toolkit samples\chatlogging directory. For more information about the sample, refer to the Chat Logging SPI Sample section of this chapter.
14
6. Use the template version in the toolkit samples\chatlogging directory to create a new Chat Logging SPI implementation.
Caution When building your chat logging DLL, leave the sample unchanged.
7. When creating 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. 8. Save the new DLL under the name StChatLog.dll. 9. Test the created DLL.
Caution Do not install a new chat logging DLL until you have tested it thoroughly; DLLs
directly affect server components operation. 10. Replace the dummy chat logging DLL on the Sametime server with the newly created DLL (StChatLog.dll). The new DLL must be placed in the default directory that contains all other DLLs. The default directory is C:\Sametime. If more than one server is included in the community, replace the DLL for each server. 11. Make the necessary changes in the stconfig.nsf file of each Sametime server in the community. For more information, see the Administration section of this chapter. 12. To activate the created chat logging DLL, 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. Starting and stopping a Sametime server on a Windows NTTM server: 1. On the Windows NT desktop, choose Start - Settings - Control Panel - Services. 2. In the Services dialog box, select Sametime server and click either Start or Stop.
Note If you installed on a Domino server, stop the Domino server to stop the Sametime
services. Starting and stopping a Sametime server on a Windows 2000 server: 1. On the Windows 2000 desktop, choose Start - Administrative Services - Component Services. 2. In the Services dialog box, select Services (Local). Right-click Sametime server and select Start or Stop.
Note If you installed on a Domino server, stop the Domino server to stop the Sametime
services. For more information on working with Sametime servers, refer to the Sametime Installation Guide and the Sametime Administrators Guide.
15
Building and Installing a Chat Logging Service Program for IBM iSeries
It is best to follow these general steps for building and installing a chat logging service program: Study the source code provided in the toolkit samples\chatlogging directory. In this Chat Logging SPI sample, each chat transcript is logged in a separate text file under a directory defined in the sametime.ini file. For more information about the sample, refer to the Chat Logging SPI Sample section of this chapter. To create a new custom Chat Logging SPI implementation, use the template version in the toolkit templates\chatlogging directory. When creating a new service program, 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 service program. To build and install the Chat Logging SPI sample that logs each chat transcript to a text file under a directory defined in the sametime.ini file, do the following: 1. Copy the following toolkit files from your local machine to a directory (for example, /STToolkit) on your IBM iSeries: samples\chatlogging\ChatResource.cpp samples\chatlogging\ChatResource.h samples\chatlogging\ChatSessionTable.cpp samples\chatlogging\ChatSessionTable.h samples\chatlogging\stDdaClApi.cpp samples\nonwin32\utilities.cpp samples\nonwin32\utilities.h samples\nonwin32\debug.h samples\nonwin32\winprofile.cpp inc\chatlogging\stDdaClApi.h inc\chatlogging\stDdaClCodes.h templates\authtoken\stAuthTokenApi.cpp inc\authtoken\stAuthTokenApi.h inc\common\stDdaApiDefs.h inc\common\nonwin32\windows.h 2. Add the ASCII C/C++ Runtime Development kit to your iSeries system. Refer to the following Web site: http://www-919.ibm.com/developer/factory/asciirt/devkit.html 3. Create a library to hold your custom service programs and modules CRTLIB CHATAPILIB 4. Compile the chatlogging source files using the following commands: CRTCPPMOD MODULE(CHATAPILIB/CHATRSC) SRCSTMF('/STToolkit/ChatResource.cpp') DBGVIEW(*SOURCE) DEFINE('QSRCSTMF' '_UNIX' 'OS400' 'qadrt_use_ctype_inline' 'V5R2_COMPILER' 'UNIX_TOOLKIT_COMPILE') TERASPACE(*YES)
16
STGMDL(*INHERIT) INCDIR('/STToolkit'
'/qibm/proddata/qadrt/include') TGTCCSID(819)
CRTCPPMOD MODULE(CHATAPILIB/CHATSESTBL) SRCSTMF('/STToolkit/ChatSessionTable.cpp') DBGVIEW(*SOURCE) DEFINE('QSRCSTMF' '_UNIX' 'OS400' 'qadrt_use_ctype_inline' 'V5R2_COMPILER' 'UNIX_TOOLKIT_COMPILE') TERASPACE(*YES) STGMDL(*INHERIT) INCDIR('/STToolkit' '/qibm/proddata/qadrt/include') TGTCCSID(819) CRTCPPMOD MODULE(CHATAPILIB/UTILITIES) SRCSTMF('/STToolkit/utilities.cpp') DBGVIEW(*SOURCE) DEFINE('QSRCSTMF' '_UNIX' 'OS400' 'qadrt_use_ctype_inline' 'V5R2_COMPILER' 'UNIX_TOOLKIT_COMPILE') TERASPACE(*YES) STGMDL(*INHERIT) INCDIR('/STToolkit' '/qibm/proddata/qadrt/include') TGTCCSID(819) CRTCPPMOD MODULE(CHATAPILIB/STDDACLAPI) SRCSTMF('/STToolkit/stDdaClApi.cpp') DBGVIEW(*SOURCE) DEFINE('QSRCSTMF' '_UNIX' 'OS400' 'qadrt_use_ctype_inline' 'V5R2_COMPILER' 'UNIX_TOOLKIT_COMPILE') TERASPACE(*YES) STGMDL(*INHERIT) INCDIR('/STToolkit' '/qibm/proddata/qadrt/include') TGTCCSID(819) CRTCPPMOD MODULE(CHATAPILIB/WINPROFILE) SRCSTMF('/STToolkit/winprofile.cpp') DBGVIEW(*SOURCE) DEFINE('QSRCSTMF' '_UNIX' 'OS400' 'qadrt_use_ctype_inline' 'V5R2_COMPILER' 'UNIX_TOOLKIT_COMPILE') TERASPACE(*YES) STGMDL(*INHERIT) INCDIR('/STToolkit' '/qibm/proddata/qadrt/include') TGTCCSID(819) 5. Create a service program called STCHATLOG in library CHATAPILIB: CRTSRVPGM SRVPGM(CHATAPILIB/STCHATLOG)
MODULE(CHATAPILIB/CHATRSC CHATAPILIB/CHATSESTBL
CHATAPILIB/UTILITIES CHATAPILIB/STDDACLAPI
CHATAPILIB/WINPROFILE) BNDSRVPGM(QADRTTS) EXPORT(*ALL)
OPTION(*DUPVAR *DUPPROC)
6. Change the object owner of the new STCHATLOG service program to QNOTES: CHGOBJOWN OBJ(CHATAPILIB/STCHATLOG) OBJTYPE(*SRVPGM)
NEWOWN(QNOTES)
7. Remove the symbolic link /QIBM/Userdata/lotus/notes/STCHATLOG.SRVPGM via the CL command: RMVLNK OBJLNK('/qibm/userdata/lotus/notes/STCHATLOG.SRVPGM'). 8. Create a new link /QIBM/Userdata/lotus/notes/STCHATLOG.SRVPGM that points to your new STCHATLOG service program in CHATAPILIB via the CL command: ADDLNK OBJ('/qsys.lib/CHATAPILIB.lib/STCHATLOG.SRVPGM')
NEWLNK('/qibm/userdata/lotus/notes/STCHATLOG.SRVPGM')
17
9. Change the authority on the new link via the CL command: CHGAUT OBJ('/QIBM/Userdata/lotus/notes/STCHATLOG.SRVPGM') USER(QNOTES) DTAAUT(*RWX) OBJAUT(*ALL) 10. Make the necessary changes in the stconfig.nsf file of each Sametime server in the community. For more information, see the Administration section of this chapter. 11. To activate the created chat logging service program, stop and start the Sametime server on which the service program is installed. If the Sametime community contains more than one Sametime server, stop and start all servers in the community. For more information on stopping and starting Sametime servers, refer to the Sametime 3.1 for iSeries Installation Guide and the Sametime 3.1 Administrators Guide.
Recommendations
When building the chat logging DLL, follow the provided template and sample as closely as possible. Follow these additional recommendations to ensure the success of your application. Chat Logging SPI functions 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 increased, and the information in the Sametime log file is updated accordingly. Use this parameter for keeping track of the used versions. See the stDdaClInit function in the Chat Logging SPI Functions section for more information on the libversion parameter. 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 for continuing to receive updates on the application statuses. See the appRetCode parameter of the stDDaClinit function in the Chat Logging SPI Functions section for more information.
Note
To prevent information loss, concatenate the messages.
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.
18
Chat Logging SPI Sample

The Chat Logging SPI sample provides an example of the synchronous implementation of the Chat Logging SPI feature. It can be found on the Directory and Database Access SPI Toolkit home page. For more information, see the Chat Logging SPI Contents section of this document. 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. The file version provides examples of constants, error messages, and additional sametime.ini flags.
Note Constants, error messages, and sametime.ini flags in the Chat Logging sample are
optional.
Sametime.ini Flags for the Chat Logging SPI Sample

These sametime.ini flags have been specially created for the Chat Logging SPI sample: The BB_CL_TRACE flag is used for recording the Chat Logging SPI sample debug messages in trace files. To enable the recording, set BB_CL_TRACE to 1. The BB_CL_LIBRARY_PATH flag (in the [Library] section) is used to specify the location for logging chat transcripts. In this sample, chat transcripts are saved in the sametime\CLData folder.
Chat Logging SPI Sample Parameters

This section describes the following: Chat Logging SPI Sample Error Messages Chat Logging SPI Sample Constants
Chat Logging SPI Sample Error Messages

These error messages were specifically developed for the Chat Logging SPI sample. For general chat logging return and error messages, refer to the Chat Logging SPI Return Messages section of this document.
Message ST_DDA_CL_SESSION_ALREADY_EXISTS Value 0x1002 Description
This message indicates that the operation could not be performed because the specified session ID is already in use.
19
Message ST_DDA_CL_SESSION_DOES_NOT_EXIST
Value 0x1003
Description
This message indicates that the indicated session ID does not exist. This message indicates that the access to the data store was denied. This message indicates that the received message string is too long and will not be logged.
ST_DDA_CL_DB_ERROR
0x1004
ST_DDA_MSG_TOO_LONG
0x1005
Chat Logging SPI Sample Constants

The following constants were specifically developed for the Chat Logging SPI sample. For information about general chat logging constants, refer to the Chat Logging SPI Reference section of this document.
Message ST_DDA_MAX_MSG_LEN Value Description
11000 characters
This parameter identifies the maximum length of the message string that can be logged. This parameter indicates the maximum length of the login name, user name and group name. This parameter indicates the maximum length of the string. This parameter indicates the maximum message size of a path or a file name. This parameter defines the file type of the files where chat transcripts are saved.
ST_DDA_MAX_NAME_LENGTH
256 characters
ST_DDA_MAX_STR_LEN
1024 characters
MESSAGE_SIZE
2048
CL_SUFFIX
.dat
20
Message LIBRARY_SECTION
Value
Description
Library
This parameter indicates the section of a sametime.ini file where the DEFAULT_LIB_PATH flag is written. This parameter indicates the default location of the folder where the chat transcripts are saved. This parameter indicates the name of the debug flag in the sametime.ini file. This flag determines the folder where chat transcripts are saved. This parameter indicates the name of the Chat Logging SPI configuration file. This parameter indicates the name and location of the trace files where the debug messages are recorded. This parameter indicates the prefix for the name of the trace file.
DEFAULT_LIB_PATH
CLData/
CL_LIBRARY_PATH
BB_CL_LIBRARY_PATH
CL_INI_FILE_NAME
sametime.ini (example)
CL_TRACE_FILE_NAME
trace/StChatLog.txt
CL_PREFIX_NAME
StChatLog
21
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.
stDdaClApi.cpp
#include #include #include #include #include #include <stDdaClCodes.h>
<ChatSessionTable.h>
<stdio.h>
<string.h>
<stDdaClApi.h>
<ChatResource.h>
"3.17.0.3"
#define VP_CL_VERSION
The dbg variable is useful to enable or disable debugging information. If dbg is equal to 1, CHAT_RSC.print() prints the debug message to the debug file. Otherwise, no debug information is printed. int dbg = CHAT_RSC.getDebugFlagValue("BB_CL_TRACE"); char *globalRetMsg = 0; StDdaRetVal *globalRetCode = 0; ChatSessionTable table; The stDdaClInit function initializes the Chat Logging SPI. By the return code, the programmer knows if the initialization succeeded or not. int ST_DDA_API stDdaClInit( /*in/out*/ int* prVersion, /*in*/ int initializedOutside, /*out*/ int* initializedInside, /*out*/ char* dirType, /*out*/ char* libVersion, /*out*/ StDdaRetVal* appRetCode, /*out*/ char* appRetMsg) { if (dirType && libVersion) { strcpy(dirType, ST_DDA_API_FILE_TYPE);
strcpy(libVersion, VP_CL_VERSION);
}
Inside the ChatSessionEntry::createPath function, the SPI creates the path where all files for each session are to be created. ChatSessionEntry::createPath();
globalRetCode = appRetCode;
globalRetMsg = appRetMsg;
*globalRetCode = ST_DDA_OK;
22
if (*prVersion < ST_DDA_CL_LIB_VERSION)

{
CHAT_RSC.print(dbg,"The received version - %d not supported, black support only version %d and up",*prVersion, ST_DDA_CL_LIB_VERSION); *globalRetCode = ST_DDA_ERROR; sprintf(globalRetMsg, "Version - %d is not supported", *prVersion); return ST_DDA_API_VERSION_MISMATCH;
}
*prVersion = ST_DDA_CL_LIB_VERSION;
If the initialization successfully completes, use the initializedInside flag for the value that describes exactly what actions were prepared during the initialization (for example, database initialization). (*initializedInside) |= initializedOutside;
CHAT_RSC.print(dbg,"Initialization complete");
return ST_DDA_API_OK;
} The stDdaClTerminate function is responsible for closing all opened sessions. Usually the server application calls this function when it fails. void ST_DDA_API stDdaClTerminate() { Inside closeAllChatSession, all opened sessions are closed. table.closeAllChatSession(); } The server application usually calls the stDdaClTimer function at regular intervals. Inside the stDdaClTimerEvent function, the SPI has a chance to do some periodic actions (for example, a database refresh or memory cache refresh). void ST_DDA_API stDdaClTimerEvent(void) { } Every time a new session is started, the server application can call to one of these functions: stDdaClSessionStarted or stDdaClSessionStartedByOrgName. int ST_DDA_API
stDdaClSessionStarted(const char* sessionId)
{
return stDdaClSessionStartedByOrgName(sessionId,"");
}
23
The server application calls the stDdaClSessionStartedByOrgName function every time a new session is started. int ST_DDA_API stDdaClSessionStartedByOrgName(/*in*/ const char* sessionId, /*in*/ const char* organization) { int rc; The SPI adds a new session to the chatSession table, opens a new file, and writes the appropriate message. If an error occurs during this operation, the SPI prints a debug message and returns the error code to the server application. rc=table.openChatSession(sessionId,organization);
if(rc==ST_DDA_CL_DB_ERROR)
{
*globalRetCode=ST_DDA_FATAL;
sprintf(globalRetMsg, "BB error - Can't open DB");
CHAT_RSC.print(dbg,"stDdaClSessionStartedByOrgName: Can't
open DB ");
}
else if(rc==ST_DDA_CL_SESSION_ALREADY_EXISTS)
{
*globalRetCode=ST_DDA_ERROR;
sprintf(globalRetMsg, "BB error - session %s already
exist", sessionId);
CHAT_RSC.print(dbg,"stDdaSessionStarted: The session - %s for organization %s already exists",sessionId, organization); } return rc; } The server application calls the stDdaClSessionEnded function every time an open session is ended. int ST_DDA_API stDdaClSessionEnded(const char* sessionId) { The SPI inserts the appropriate message to that session file and removes the session entry from the chatSession table. If an error occurs during this operation, the SPI prints a debug message and returns the error code to the server application. int rc = table.closeChatSession(sessionId);
if(rc > 0)
{
sprintf(globalRetMsg, "SPI close session <%s> <0x%x>",sessionId,rc);
}
return rc;
}
error
24
When a new entity joins an open session, the server application calls the stDdaClJoiningSession function. int ST_DDA_API stDdaClJoiningSession( /*in*/ const char* sessionId, /*in*/ const StDdaClEntity *entity, /*in*/ const StDdaClEntity *scope) { int rc; ChatSessionEntry* entry; The SPI tries to find a session handler in the chatSession table by the sessionId. If no error occurs, the appropriate message is written to the session file. entry=table.findChatSession(sessionId);
if(entry)
{
The addUser function writes the proper message to the session file. rc=entry->addUser(entity,scope);
{
*globalRetCode=ST_DDA_FATAL; sprintf(globalRetMsg, "BB error - Can't open DB"); CHAT_RSC.print(dbg,"stDdaClJoiningSession: Can't open DB ");
}
}
Otherwise, the appropriate debug message is printed in the trace file, and an error code is returned to the server application. else { *globalRetCode=ST_DDA_ERROR; sprintf(globalRetMsg, "BB error - session %s doesn't exist", sessionId); CHAT_RSC.print(dbg,"stDdaClJoiningSession: Session - %s doesn't exist ", sessionId); return ST_DDA_CL_SESSION_DOES_NOT_EXIST;
}
return rc;
} When an entity is leaving an open session, the server application calls the stDdaClLeavingSession function. int ST_DDA_API stDdaClLeavingSession( /*in*/ const char* sessionId, /*in*/ const StDdaClEntity *entity) { int rc; ChatSessionEntry* entry;
25
The SPI tries to find the session handler in the chatSession table by the sessionId. If no error occurs, the appropriate message is written to the session file. entry=table.findChatSession(sessionId);
if(entry)
{
The removeUser function writes the proper message to the session file. rc=entry->removeUser(entity);
{
CHAT_RSC.print(dbg,"stDdaSessionEnded: Can't open DB ");
}
}
Otherwise, the appropriate debug message is printed in the debug file, and an error code is returned to the server application. else {
sprintf(globalRetMsg, "BB error - session %s doesn't
exist",sessionId); CHAT_RSC.print(dbg,"stDdaClLeavingSession: Session - %s doesnt exist ", sessionId); return ST_DDA_CL_SESSION_DOES_NOT_EXIST;
}
return rc;
} The stDdaClSessionMsg function is responsible for writing the message that comes from the server application to the appropriate session file. int ST_DDA_API stDdaClSessionMsg(/*in*/ const char* sessionId, /*in*/ const StDdaClEntity *sender, /*in*/ unsigned long msgLen, /*in*/ const char *msg, /*in*/ const StDdaClEntity *receiver) { int rc; ChatSessionEntry* entry; The SPI tries to find the session handler in the chatSession table by the sessionId. If no error occurs, the appropriate message is written to the session file. entry=table.findChatSession(sessionId);
if(entry)
{
26
The message function writes the proper message to the session file. rc=entry->message(sender,msgLen,msg,receiver);
{
CHAT_RSC.print(dbg,"stDdaClSessionMsg: Can't open DB ");
}
if(rc==ST_DDA_MSG_TOO_LONG)
{
sprintf(globalRetMsg, "BB error - Message too long!");
CHAT_RSC.print(dbg,"stDdaClSessionMsg: Message too long!");
}
}
Otherwise, the appropriate debug message is printed in the trace file and an error code is returned to the server application. else {
sprintf(globalRetMsg, "BB error - %s doesnt exist ",
sessionId); CHAT_RSC.print(dbg,"stDdaClSessionMsg: Session - %s doesnt exist ", sessionId); return ST_DDA_CL_SESSION_DOES_NOT_EXIST;
}
return rc;
}
ChatResource.h
#ifndef __CHATRESOURCE_H__
#define __CHATRESOURCE_H__
#include <stDdaClCodes.h>
#define CHAT_RSC (ChatResource::instance())
The ChatResource class is responsible for: Getting all the ini flags from sametime.ini Creating the default path for session files Printing debug messages to the trace file Getting the current time string
27
class ChatResource { public: //Ctor + Dtor ChatResource();

~ChatResource() {};
private://members char defaultPath[ST_DDA_MAX_NAME_LENGTH]; char tracePath[ST_DDA_MAX_NAME_LENGTH]; char controlPath[ST_DDA_MAX_NAME_LENGTH]; char iniFile[ST_DDA_MAX_NAME_LENGTH]; public://members FILE * traceFile; private://functions void createDefaultPath(void); void createStrControlPath(void); public:// functions const char* getDefaultPath(void); const char* getStrControlPath(void); void print(int flag,const char* format, ...); int getDebugFlagValue(const char* id); const char* getCurTime(void); public://Single Tone static ChatResource* m_ptr; static ChatResource& instance() { if(!m_ptr) m_ptr=new ChatResource(); return *m_ptr; } }; #endif //__CHATRESOURCE_H__
ChatResource.cpp
#include <string.h>
#include <stdio.h>
#if !defined (_UNIX)
#include <conio.h>
#endif
#include <stdlib.h>
#include <stdarg.h>
#include <sys/types.h>
#include <time.h>
#include <windows.h>
#include <ChatResource.h>
28
#if defined(_UNIX) #include <utilities.h> #endif ChatResource* ChatResource::m_ptr = 0; // ChatResource Constructor ChatResource::ChatResource() { defaultPath[0] = '\0'; controlPath[0] = '\0'; iniFile[0] = '\0'; tracePath[0] = '\0'; createDefaultPath(); } The ChatResource::createDefaultPath function creates the default path for session files and the path for the sametime.ini file and the trace file. void ChatResource::createDefaultPath() { if (defaultPath[0] == '\0') { char s[ST_DDA_MAX_NAME_LENGTH]; char szFilename[MESSAGE_SIZE]; #if defined(_UNIX) GetDataDirectory(szFilename); strcat(szFilename, "/"); strcpy(defaultPath, szFilename);
#else
DWORD mod = GetModuleFileName(0, szFilename, sizeof(szFilename)); if (!mod) return ;
strcpy(s,szFilename);
char* i = strrchr(s,'\\');
if(i == NULL) strcpy(s,'\0');
else
{
strncpy(defaultPath,s,(i - s + 1)); defaultPath[i - s + 1 ]='\0'; } if (s[0] == '\0') { strcpy(defaultPath,"./");
defaultPath[2]='\0';
}
#endif
29
if( iniFile[0] == '\0') {

strcpy(iniFile,defaultPath);
strcat(iniFile,CL_INI_FILE_NAME);
}
if( tracePath[0] == '\0')
{
strcpy(tracePath,defaultPath);
strcat(tracePath,CL_TRACE_FILE_NAME);
}
strcat(defaultPath,DEFAULT_LIB_PATH);
}
return;
} The ChatResource::getDefaultPath function returns the default path. If the default path does not exist, it is created first. const char* ChatResource::getDefaultPath(void) { if( defaultPath[0] == '\0') createDefaultPath(); return defaultPath; } The ChatResource::createStrControlPath function creates the path for all session files. void ChatResource::createStrControlPath() { createDefaultPath(); char buf[256] = ""; GetPrivateProfileString(LIBRARY_SECTION,CL_LIBRARY_PATH,0, buf, 256, iniFile);
strcpy(controlPath,buf);
return;
} The ChatResource::getStrControlPath function returns the control path where the session files are created. If the control path does not exist, it is created first. const char* ChatResource::getStrControlPath() { if (controlPath[0] == '\0') createStrControlPath(); return controlPath; } The ChatResource::getDebugFlagValue function returns the debug flag value. int ChatResource::getDebugFlagValue(const char* id) { return GetPrivateProfileInt(DEBUG_SECTION, id, 0, iniFile); }
30
The ChatResource::print function creates the debug message and writes it to the trace file. void ChatResource::print(int flag,const char* format, ...) { if(flag) { char msg[MESSAGE_SIZE]; sprintf(msg, "%-20.20s %s ",CL_PREFIX_NAME, getCurTime()); #ifdef _WIN32 wvsprintf(msg+strlen(msg), format, (LPSTR)(&format+1)); #else va_list args; va_start( args, format ); (void) vsprintf( msg+strlen( msg ), format, args ); va_end( args ); #endif
traceFile = fopen(tracePath, "a+");
if(traceFile)
{
fprintf(traceFile, "%s\n", msg);
fflush(traceFile);
fclose(traceFile);
}
}
return;
} The ChatResource::getCurTime function creates and returns the current time string. const char* ChatResource::getCurTime(void) { static char buf[30]; time_t t = time(0); strftime(buf, 30,"%d/%b/%y, %H:%M:%S",localtime(&t)); return buf; }
ChatSessionTable.h
#ifndef __CHATSESSIONTABLE_H__ #define __CHATSESSIONTABLE_H__ #pragma warning(disable:4786) // identifier was truncated to '255' characters in the browser information
31
#if !defined(UNIX_TOOLKIT_COMPILE) #ifdef _UNIX #include "ubique.h" #endif #else // TOOLKIT_COMPILE #include "windows.h" #endif // UNIX_TOOLKIT_COMPILE #include <map>
#include <string>
#if defined(_WINDOWS) || defined(_CONSOLE)
using namespace std; #else USING_NAMESPACE(std); #endif #include "stDdaClApi.h" class ChatSessionEntry; The ChatSessionTable class is a manager of all open sessions. class ChatSessionTable { public: map<string, ChatSessionEntry *, less<string> > m_map; public://Ctor & Dtor ChatSessionTable(); virtual ~ChatSessionTable(){}; public://functions int openChatSession(string key,string organization); int closeChatSession(string key); void closeAllChatSession(void); ChatSessionEntry* findChatSession(string key); }; The ChatSessionEntry class represents a single session. class ChatSessionEntry { private: string m_key;
string m_organization;
static string path;
public: FILE * static static static
sessionFile; void createPath(); char set[10]; const char* getSet(void){return set;}
32
string filePath; public: ChatSessionEntry(string key,string organization); virtual ~ChatSessionEntry(); public: string getKey(void){return m_key;}; FILE * getSessionFile(void){return sessionFile;}; #if defined(OS400) void getEntityType(StClEntityType entity, char * entityType); #else void getEntityType(const StClEntityType entity,char* entityType); #endif bool openFile(); bool closeFile(); int startSession(); int endSession(); int addUser(const StDdaClEntity * entity,
const StDdaClEntity * scope);
int removeUser(const StDdaClEntity * entity); int message(const StDdaClEntity * sender,
unsigned long msgLen,
const char* msg,
const StDdaClEntity * receiver);
}; #endif //__CHATSESSIONTABLE_H__
ChatSessionTable.cpp
#include <ChatSessionTable.h> #include <ChatResource.h> #include <stDdaClCodes.h> #pragma warning(disable:4786) // identifier was truncated to '255' characters in the browser information
33
extern int dbg; string ChatSessionEntry::path; char ChatSessionEntry::set[] = {'/','\\',':','*','?','\"','<','>','|',' '}; The constructor of the ChatSessionTable class is: ChatSessionTable::ChatSessionTable()
{
}
Use the ChatSessionTable::openChatSession function to check to see if the session exists in the chatSession table. If it does not exist, create and start the session. int ChatSessionTable::openChatSession( string key, string organization) { if (findChatSession(key)) return ST_DDA_CL_SESSION_ALREADY_EXISTS; To add a new session to the chatSession table, use ChatSessionEntry: ChatSessionEntry* entry = new ChatSessionEntry(key, organization); m_map.insert(map<string, ChatSessionEntry *, less<string> > ::value_type(key,entry)); Start the session: return entry->startSession(); } Use the ChatSessionTable::closeChatSession function for closing the existing session when it ends: int ChatSessionTable::closeChatSession(string key) { ChatSessionEntry* entry = 0; int rc = ST_DDA_CL_SESSION_DOES_NOT_EXIST; Find the session handler in the session table: map<string, ChatSessionEntry *, less<string> > ::iterator iter = m_map.find(key);
if (iter != m_map.end())
{
entry = (ChatSessionEntry *)((*iter).second);
// end session
rc = entry->endSession();
m_map.erase(iter);
}
else
34
Print the debug message in the trace file if the session is not found. CHAT_RSC.print(dbg,"ChatSessionTable::closeChatSession: Session %s doesn't exist ",key.c_str()); return rc; } The ChatSessionTable::closeAllChatSession function deletes all the entries from the ChatSession table. void ChatSessionTable::closeAllChatSession(void) { CHAT_RSC.print(dbg,"ChatSessionTable::closeAllChatSession: processing..."); m_map.clear(); } The ChatSessionTable::findChatSession function finds and returns the session handler by the sessionId in the session table. ChatSessionEntry* ChatSessionTable::findChatSession(string key) { ChatSessionEntry* entry = 0; map<string, ChatSessionEntry *, less<string> >::iterator iter = m_map.find(key); if (iter != m_map.end())
entry = (ChatSessionEntry *)((*iter).second);
return entry; } The ChatSessionEntry::createPath function creates the path where all session files are to be created. This static function is called only once when the first session is opened. void ChatSessionEntry::createPath() { if ( !path.empty()) return;
// get path from sametime.ini file.
string controlPath = CHAT_RSC.getStrControlPath();
// if no path was defined in sametime.ini get the default path. if(controlPath.empty()) controlPath = CHAT_RSC.getDefaultPath(); path = controlPath;
35
int length = path.size();

#ifdef OS400
if (!(path[length-1] == '/'))
path.append("/");
#else
if (!(path[length-1] == '\\'))
path.append("\\");
#endif
return; } The ChatSessionEntry constructor is: ChatSessionEntry::ChatSessionEntry(string key, string organization): sessionFile(0), m_organization(organization) { //create full path (with file name) of new session. m_key=key; string temp; temp=key; temp+="_"; temp.append(CHAT_RSC.getCurTime()); temp.append(CL_SUFFIX); int length = temp.size(); for( int index = temp.find_first_of( ChatSessionEntry::getSet()); index != -1; index = temp.find_first_of( ChatSessionEntry::getSet())) temp[index] = '_';
filePath = path;
filePath.append(temp);
} The ChatSessionEntry destructor is: ChatSessionEntry::~ChatSessionEntry()
{
// if session file remain open - close it
if (sessionFile) fclose(sessionFile); } Use the ChatSessionEntry::openFile function to open the session file for writing. bool ChatSessionEntry::openFile() { #ifdef OS400 #ifdef UNIX_TOOLKIT_COMPILE sessionFile = fopen(filePath.c_str(), "ab+"); #else sessionFile = fopen(filePath.c_str(), "a+, codepage=819"); #endif // UNIX_TOOLKIT_COMPILE
Instant Messaging and Web Conferencing Directory and Database Access Toolkit Developers Guide 36
#else sessionFile = fopen(filePath.c_str(), "a+");

#endif
if (!sessionFile)
return false; return true; } Use the ChatSessionEntry::closeFile function to close the session file. bool ChatSessionEntry::closeFile() { if (!sessionFile) return false;
fclose(sessionFile);
return true;
} Use the ChatSessionEntry::getEntityType function to convert the entity type to a suitable string. void ChatSessionEntry::getEntityType(StClEntityType entity, char* entityType) { if( !entityType ) CHAT_RSC.print(dbg,"ChatSessionEntry::getEntityType: empty entityType "); switch (entity)
{
case(ST_DDA_CL_USER):
strcpy(entityType,"User");
break;
case(ST_DDA_CL_SECTION):
strcpy(entityType,"Section");
break;
case(ST_DDA_CL_ACTIVITY):
strcpy(entityType,"Activity");
break;
case(ST_DDA_CL_SESSION):
strcpy(entityType,"Session");
break;
default: strcpy(entityType,"Unknown"); } }
37
Use the ChatSessionEntry::startSession function to write a "start" message to the appropriate session file. int ChatSessionEntry::startSession() { if (!openFile()) { If the session cannot open the session file, a debug message is printed to the trace file, and the function error code is returned. CHAT_RSC.print(dbg,"startSession: Can't create %s", filePath.c_str()); return ST_DDA_CL_DB_ERROR;
}
int rc = fprintf(sessionFile, "\n%s: Session started for
organization %s",
CHAT_RSC.getCurTime(),m_organization.c_str());
closeFile();
if (rc < 0)
return ST_DDA_API_INTERNAL_ERROR; return ST_DDA_API_OK; } Use the ChatSessionEntry::endSession function to write an "end" message to the appropriate session file. int ChatSessionEntry::endSession() { if (!openFile()) { If the session cannot open the session file, a debug message is printed to the trace file, and the function error code is returned. CHAT_RSC.print(dbg,"endSession: Can't open %s ",
filePath.c_str());
return ST_DDA_CL_DB_ERROR;
}
int rc = fprintf(sessionFile, "\n%s: Session ended", CHAT_RSC.getCurTime());
int error = fprintf(sessionFile, "\n***************\n");
closeFile();
if (rc<0 || error < 0)
return ST_DDA_API_INTERNAL_ERROR; return ST_DDA_API_OK; }
38
Use the ChatSessionEntry::addUser function to write an "add user" message to the appropriate session file. int ChatSessionEntry::addUser(const StDdaClEntity * entity, const StDdaClEntity * scope) { if (!openFile()) { If the session cannot open the session file, a debug message is printed to the trace file, and the function error code is returned. CHAT_RSC.print(dbg,"addUser: Can't open %s ",
filePath.c_str());
}
char entityType[ST_DDA_MAX_NAME_LENGTH];
char scopeType[ST_DDA_MAX_NAME_LENGTH];
char line[ST_DDA_MAX_STR_LEN];
Find the entity type string. getEntityType(entity->type, entityType); if(scope)
{
Find the scope type string. getEntityType(scope->type, scopeType); Create the string with the entity information and the scope type. This string is written to the session file. sprintf(line, "\n%s: Add %sId %s to %sId %s",
CHAT_RSC.getCurTime(),
entityType,
entity->id,
scopeType,
scope->id);
}
else
39
Otherwise, create this string containing the time and entity only. This string is written to the session file. sprintf(line, "\n%s: Add %sId %s ",
entityType,
entity->id);
int rc = fprintf(sessionFile, "%s", line);
closeFile();
if (rc < 0)
return ST_DDA_API_INTERNAL_ERROR; return ST_DDA_API_OK; } Use the ChatSessionEntry::removeUser function to write a "remove user" message to the appropriate session file. If the session cannot open the session file, a debug message is printed to the trace file, and a function error code is returned. int ChatSessionEntry::removeUser(const StDdaClEntity *entity) { if (!openFile()) { CHAT_RSC.print(dbg,"removeUser: Can't open %s ",
filePath.c_str());
}
Find the entity type string. getEntityType(entity->type, entityType);
char line[ST_DDA_MAX_STR_LEN];
Create the string that is written to the session file. sprintf(line, "\n%s: Remove %sId %s ",
entityType,
entity->id);
int rc = fprintf(sessionFile,"%s", line);
closeFile();
if (rc < 0)
40
Use the ChatSessionEntry::message function to write a message to the appropriate session file. If the session cannot open the file, a debug message is printed to the trace file, and an error code is returned. int ChatSessionEntry::message(const StDdaClEntity *sender, unsigned long msgLen, const char* msg, const StDdaClEntity *receiver) { int index; if (!openFile()) { CHAT_RSC.print(dbg,"message: Can't open %s ",
filePath.c_str());
}
if(!sender)
{
CHAT_RSC.print(dbg,"message: session <%s> - null pointer
sender",getKey().c_str());
return ST_DDA_API_INTERNAL_ERROR;
}
char line[ST_DDA_MAX_MSG_LEN];
int rc = 0;
Find the entity type string. getEntityType(sender->type, entityType); Create the string that is written to the session file. index = sprintf(line, "\n%s: Send Message from %sId %s ",
entityType,
sender->id);
if (!receiver) If the entity is All (all users in this session), create this string to be written to the session file. index += sprintf(line, "%s to All ", line);
else
{
Otherwise, find the receiver entity type string and create this ID string to be written to the session file. getEntityType(receiver->type, entityType); index += sprintf(line, "%s to %sId %s ", line, entityType, receiver->id); }
41
Create the message string that is written to the session file. #ifdef OS400
#define MAXSTRING_a 2046
if (strlen(line) + msgLen < MAXSTRING_a)
{
index += sprintf(line + index, "msgLen %id msg: %s ", msgLen,msg);
}
else
{
// need to split up the msg and log it in 2046 byte chunks
int copiedLen = MAXSTRING_a - strlen(line);
char temp[MAXSTRING_a+1];
strncpy(temp, msg, copiedLen);
// write first 2046 chars
index += sprintf(line + index, "%s", temp);
for (int n = copiedLen; n < msgLen; n += MAXSTRING_a)
{
rc = fprintf(sessionFile,"%s",line);
strcpy(line,"");
strncpy(temp,"",MAXSTRING_a+1);
strncpy(temp, &msg[copiedLen], MAXSTRING_a);
sprintf(line, "%s",temp);
copiedLen += strlen(line);
}
}
#else
index += sprintf(line + index, "msgLen %id msg: %s ",
msgLen,msg);
#endif
rc = fprintf(sessionFile, "%s", line);
closeFile();
if (rc < 0)
42
Chat Logging SPI Reference

This section describes the Chat Logging SPI Parameters and the Chat Logging SPI Functions.
Chat Logging SPI Parameters

This section contains information about: Chat Logging SPI Return Messages Chat Logging SPI Constants
Chat Logging SPI Return Messages

The table below lists and describes the return messages common to all Sametime Toolkit SPIs, APIs, and DLLs, including the Chat Logging SPI.
Return message ST_DDA_API_OK Value 0x0000 Description
Returned by the SPI functions when the requested operation succeeds 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, and so on) 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
ST_DDA_API_VERSION_MISMATCH
0x0001
ST_DDA_API_INVALID_PARAM
0x0002
ST_DDA_API_INTERNAL_ERROR
0x0003
ST_DDA_API_NOT_SUPPORTED
0x0004
43
Chat Logging SPI Constants

The table below lists and describes the constants defined in stDdaApiDefs.h that are common to all Sametime toolkit SPIs and APIs, including the Chat Logging SPI.
Name ST_DDA_MAX_NAME_LENGTH Value Description
256 characters
This constant defines the maximum length of the login name, user name, and group name. This constant defines the maximum length of a user ID or group ID. This constant defines the maximum length of a user description or a group description string. These constants are used to 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).
ST_DDA_MAX_ID_LENGTH
256 characters
ST_DDA_MAX_DESCRIPTION_LENGTH
256 characters
ST_DDA_API_NOTES, ST_DDA_API_LDAP
0x0002, 0x0004
respectively
44
Chat Logging SPI Functions

This section describes the Chat Logging SPI functions provided by this toolkit. The Sametime Chat Logging SPI provides the following functions: stDdaClInit stDdaClTerminate stDdaClTimerEvent stDdaClSessionStarted stDdaClSessionEnded stDdaClEntity stClEntityType stDdaClJoiningSession stDdaClLeavingSession stDdaClSessionMsg
stDdaClInit
Overview The stDdaClInit function allows the Chat Logging SPI to perform preparations that are necessary to support its regular functionality. The function also checks for anything preventing the SPI from supplying this functionality. The syntax for the initialization call is:
int ST_DDA_API stDdaClInit (/*in/out*/
/*in*/
/*out*/
/*out*/
/*out*/
/*out*/
/*out*/
int* prVersion, int initializedOutside, int* initializedInside, char* dirType, char* libVersion, StDdaRetVal* appRetCode, char* appRetMsg ) ;
45
Description The stDdaClInit function initializes the chat logging library and verifies that it can handle the specified version of the SPI. The calling application places the SPI version number in the prVersion parameter. The chat logging library places its SPI version number. If the 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 if it can work with an SPI of a lower version. 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 if it can work with an SPI of a lower version. Depending on the particular configuration, the initialization either continues, or an error message is returned. The initializeOutside parameter contains information about platform interfaces that are initialized by this calling application.
Note One server application can use several libraries, and some platform interfaces must be
initialized only once per server application. If the initializeOutside parameter indicates that the platform interface was already initialized, the initialization process does not continue and an OK message is returned. If the platform interface was not initialized, the chat logging library performs the initialization and sets one of the bits in the initializedInside mask accordingly. The initializeInside parameter contains information about platform interfaces that must be initialized and it keeps an internal record of the initialized interfaces.
46
Parameters - Input prVersion Determines which SPI versions are used by the calling application (Chat Logging server application) and the chat logging library. This parameter is also an output parameter. Sametime 2.5 supports prVersion=11; Sametime 2.6 supports prVersion=11 or 12. See stDdaClSessionStartedByOrgName for specific information about the prVersion parameter pertaining to that function. initializedOutside Describes the platform interfaces initialized by other libraries that this server application might have used before calling this function. Examples of this parameter are ST_DDA_API_NOTES for the Notes platform interface and ST_DDA_API_LDAP for the LDAP platform interface.
Parameters - Output initializedInside This bit mask describes platform interfaces that were initialized by this library. It is used in conjunction with the InitializedOutside parameter; the function decides what interfaces still need to be initialized based on the value of the InitializedOutside parameter. The function then keeps an internal record of the interfaces that it initialized and sets the InitializedInside parameter accordingly. This parameter identifies the library and is recorded in the sametime.log. Any change in the library type is updated in the sametime.log. This string identifies the library version. The libVersion parameter is recorded in the sametime.log. Any change in the library version is updated in the sametime.log This pointer points to a variable that holds the return code from the most recent call to one of the librarys functions.
dirType
libVersion
appRetCode
47
appRetMsg
This pointer points to a string variable (null-terminated) that holds a message containing any information about what happened during the most recent call to one of the librarys functions.
Note The maximum length of this message is 1023 characters (buffer maximum length is 1024).
Return Values
ST_DDA_API_OK 0x0000
Indicates that the initialization succeeded Indicates that the library does not support the given version of the calling application Indicates that the initialization failed Indicates that the library does not support this SPI version of the calling application
ST_DDA_AIP_VERSION_MISMATCH
0x0001
0x0003
0x0004
stDdaCITerminate
Overview The stDdaClTerminate function allows the developer to perform an efficient shutdown by freeing memory and any other resources that were being used by the application. The syntax for the termination call is:
void ST_DDA_API stDdaClTerminate()
Description This function terminates any platform interface initialized by the library. It uses a copy of the value of the initializedInside parameter that was saved when stDdaClInit was called. Parameters - Input None
48
Parameters - Output None Return Values none
stDdaClTimerEvent
Overview The stDdaClTimerEvent function allows the library to perform actions that are time-based, such as refreshing a cache or reconnecting to the database. The syntax for the timer event call is:
void ST_DDA_API stDdaClTimerEvent(void)
Description This function is called at the defined interval (for example, once per minute) by the calling application, enabling time-based actions. Parameters Input none Parameters - Output none Return Values none
stDdaClSessionStarted
Overview The stDdaClSessionStarted function allows the SPI developer to perform certain preparations for new session logging.
49
The syntax for this call is:

int ST_DDA_API
stDdaClSessionStarted (/*in*/ const char* sessionId)
Description This function is called when a new chat session is started in an instant message or a Place (a meeting or n-way chat). Parameters - Input sessionId This parameter is an identifier of the chat session. It is used in subsequent calls relating to the same session.
Parameters - Output none Return Values

Indicates that the action succeeded

Indicates that the ID defined
ST_DDA_CL_SESSION_ALREADY_EXIST
0x1002
for a new session is already in use

ST_DDA_CL_DB_ERROR 0x1004
Indicates a failure to write to the data store
Note If the server is configured to work in strict mode and the Chat Logging SPI function
returns errors, all existing IMs and chats in Places will be destroyed.
stDdaClSessionStartedByOrgName
Overview The stDdaClSessionStartedByOrgName function allows the SPI developer to perform certain preparations for new session logging. This function is similar to stDdaClSessionStarted, and allows for chat logging in a hosted environment where multiple organizations use a single Sametime server. If implemented, the prVersion in the function stDdaClInit should be set to 12.
Note This function was added in Sametime 2.6, and is not required to be implemented in nonhosted environments. In this case, the prVersion in the function stDdaClInit should be set to 11.
50
The syntax for the session started call is as follows:

int ST_DDA_API stDdaClSessionStartedByOrgName (/*in*/ const char* sessionId /*in*/ const char* organization)
Description This function is called when a new chat session is started in an instant message or a Place. Parameters - Input sessionId An identifier of the chat session. It is used in subsequent calls relating to the same session. The organization name.
organization Parameters - Output none Return Values

ST_DDA_API_OK
0x0000
Indicates that the action succeeded

Indicates that the ID defined
ST_DDA_CL_SESSION_ALREADY_EXIST
0x1002
for a new session is already in use

ST_DDA_CL_DB_ERROR 0x1004
Indicates a failure to write to the data store
stDdaClSessionEnded
Overview The stDdaClSessionEnded function allows the SPI developer to perform certain operations for ending the session logging. The syntax for this call is:
int ST_DDA_API
stDdaClSessionEnded(/*in*/ const char* sessionId);
51
Description This function is called when a session is finished because the IM channel is closed or a Place is closed. Parameters - Input sessionId Parameters - Output none Return Values
ST_DDA_API_OK ST_DDA_CL_SESSION_NOT_EXIST 0x0000 0x1003
An identifier of the chat session
Indicates that the action succeeded Indicates that the defined session ID does not exist
Common Structures
The following calls use the common structures stDdaClEntity and StClEntityType: stDdaClJoiningSession stDdaCILeavingSession stDdaClSessionMsg
stDdaClEntity
The following structure describes a participant in a chat session:
struct StDdaClEntity {
char id[ST_DDA_MAX_NAME_LENGTH];
StClEntityType type;
};
52
StClEntityType
This enumerator defines the different types of participants:
typedef enum {
ST_DDA_CL_NO_TYPE,
ST_DDA_CL_USER,
ST_DDA_CL_SECTION,
ST_DDA_CL_ACTIVITY,
ST_DDA_CL_SESSION
} StClEntityType;
stDdaClJoiningSession
Overview The stDdaClJoiningSession function is used to identify the scope that each new participant is joining. The new participant can be a user, a section, or an activity. The participant can: Send and receive messages. Receive messages sent directly to the participant or to the scope in which the participant is included. The syntax for this call is:
int ST_DDA_API stDdaClJoiningSession(/*in*/ const char* sessionId, /*in*/ const StDdaClEntity *entity, /*in*/ const StDdaClEntity *scope)
Description This function is called when a participant creates or joins an IM or Place chat session. Parameters - Input sessionId entity An identifier of the chat session. An identifier of the new participant, consisting of a type and an ID. A new participant can be a section, an activity, or a user. An identifier of the scope that the new participant joins. The scope can be a user, a section, a session, or an activity.
scope
Parameters - Output none
53
Return Values
ST_DDA_API_OK ST_DDA_CL_DB_ERROR 0x0000 0x1004
Indicates that the action succeeded. Indicates that the access to the data store was denied. Failure to write to the data store. Indicates that the session with a defined ID does not exist.
ST_DDA_CL_SESSION_NOT_EXIST
0x1003
Note
If the server is configured to work in strict mode and the Chat Logging SPI function returns errors, all existing IMs and chats in Places will be destroyed.
stDdaClLeavingSession
Overview The stDdaClLeavingSession function is used to identify the participant who is leaving a session. This participant can no longer send or receive messages. The syntax for this call is:
int ST_DDA_API stDdaClLeavingSession( /*in*/ const char* sessionId, /*in*/ const StDdaClEntity *entity)
Description This function is called when a participant leaves a chat session. Parameters - Input sessionId entity An identifier of the chat session. An identifier of the leaving participant. The participant can be a section, an activity, or a user.
54
Return Values
Indicates that the action succeeded. Indicates that access to the data store was denied. Failure to write to the data store. Indicates that the session with a defined ID does not exist.
ST_DDA_CL_DB_ERROR
0x1004
0x1003
Note
stDdaClSessionMsg
Overview The stDdaClSessionMsg function is used to identify the source destination and content of the message. The syntax for this call is:
int ST_DDA_API stDdaClSessionMsg(/*in*/ /*in*/ /*in*/ /*in*/ /*in*/ const char* sessionId,
const StDdaClEntity *sender,
unsigned long msgLen,
const char *msg,
const StDdaClEntity *receiver);
Description This function is called when a participant receives a message.
55
Parameters - Input sessionId sender An identifier of the chat session. An identifier of the sender of the message. The sender can be a user, a section, a session, or an activity. The length of the message being read from the message buffer. The body of the message. An identifier of the receiver of the message. The receiver can be a user, a section, a session, or an activity.
msgLen
msg receiver
Parameters - Output none Return Values

ST_DDA_API_OK ST_DDA_CL_DB_ERROR 0x0000 0x1004
Indicates that the action succeeded. Indicates that the access to the data store was denied. Failure to write to the data store. Indicates that the length of the message exceeds the defined length. Indicates that the session with a defined ID does not exist.
ST_DDA_MSG_TOO_LONG
0x1005
0x1003
Note
56
Chapter 3 Token Authentication SPI

Introduction
Sametime uses authentication by token to authenticate connections that occur after a user has authenticated once using basic password authentication. Authentication by token prevents a user from having to re-enter authentication credentials. Sametime supports two types of authentication tokens out-of-the-box: 1) Proprietary Sametime token 2) LTPA token supported by Domino and WebSphere For additional information on these authentication tokens, see the Sametime 3.1 Administrators Guide. The Sametime Token Authentication Server Provider Interface (SPI) is a new server-side Sametime feature that allows you to customize Sametime for a different kind of token generated in your deployment by developing a DLL or service program that implements the specified SPI.
Getting Started
The Token Authentication SPI is part of the Directory and Database Access Toolkit. The Chat Logging SPI is part of the Directory and Database Access Toolkit. To install the toolkit, visit http://www.ibm.com/developerworks/lotus/products/. On the Products page, click Lotus Instant Messaging and Web Conferencing (Sametime). The Lotus Instant Messaging and Web Conferencing (Sametime) page contains links to all the documentation and downloads. 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 index.html in the toolkit root folder. Assuming that the toolkit is installed in \<server data directory>\domino\html\ST651DDAToolkit, you can access the toolkit home page at http://<server hostname>/ST651DDAToolkit/index.html.
57
Token Authentication SPI Contents

The contents of the Directory and Databases Access Toolkit that concern the Token Authentication SPI are: Sametime Directory and Database Access SPI documentation This document Token Authentication SPI template This template or dummy version of the Token Authentication SPI does not verify a token or generate a token, and it always returns OK. Use this template version for building a new Token Authentication SPI implementation. Token Authentication SPI header files These files contain SPI definitions, syntax, variables, constants, return values, and so on.
Building the Token Authentication DLL or Service Program

This toolkit does not provide a full version of the Token Authentication DLL or service program. Use the Token Authentication SPI template to complete development of the Token Authentication SPI for your particular environment(s). When creating the Token Authentication DLL or service program: Follow the interface defined by the Token Authentication SPI. Develop a mechanism for token generation and verification. To ensure proper operation of the Token Authentication DLL or service program, see the following topics: General Considerations Building and Installing a Token Authentication DLL for Windows Building and Installing a Token Authentication Service Program for IBM iSeries Recommendations
General Considerations
When deploying a Token Authentication DLL or service program in a distributed community, each server must be able to verify a token generated by others.
58
Building and Installing a Token Authentication DLL for Windows

Follow these general steps for building and installing a Token Authentication DLL: 16. Use the template version in the toolkit templates\authtoken directory to create a new Token Authentication SPI implementation. 17. When creating 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. 18. Save the new DLL under the name StAuthToken.dll. 19. Test the created DLL.
Caution Do not install a new Token Authentication DLL until you have tested it thoroughly;
DLLs directly affect server components operation. 20. Stop the Sametime server on which the DLL is installed. If the Sametime community contains more than one Sametime server, stop all servers in the community. 21. Replace the existing Token Authentication DLL on the Sametime server with the newly created DLL (StAuthToken.dll). The new DLL must be placed in the default directory that contains all other DLLs. The default directory is C:\Sametime. If more than one server is included in the community, replace the DLL for each server. 22. Start the Sametime server on which the DLL is installed. If the Sametime community contains more than one Sametime server, start all servers in the community. Starting and stopping a Sametime server on a Windows NT server: 1. On the Windows NT desktop, choose Start - Settings - Control Panel - Services. 2. In the Services dialog box, select Sametime server and click either Start or Stop. Starting and stopping a Sametime server on a Windows 2000 server: 1. On the Windows 2000 desktop, choose Start - Administrative Services - Component Services. 2. In the Services dialog box, select Services (Local). Right-click Sametime server and select Start or Stop. For more information on working with Sametime servers, refer to the Sametime 3.1 Installation Guide and the Sametime 3.1 Administrators Guide.
59
Building and Installing a Token Authentication Service Program for IBM iSeries
Follow these general steps for building and installing a Token Authentication service program: To create a new custom Token Authentication SPI implementation, use the template version in the toolkit templates/authtoken directory. When creating a new service program, 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 service program. To build and install the Token Authentication SPI sample, do the following: 23. If you have not already done so: Copy the following toolkit files from your local machine to a directory (for example, /STToolkit) on your IBM iSeries: samples\chatlogging\ChatResource.cpp samples\chatlogging\ChatResource.h samples\chatlogging\ChatSessionTable.cpp samples\chatlogging\ChatSessionTable.h samples\chatlogging\stDdaClApi.cpp samples\nonwin32\utilities.cpp samples\nonwin32\utilities.h samples\nonwin32\debug.h samples\nonwin32\winprofile.cpp inc\chatlogging\stDdaClApi.h inc\chatlogging\stDdaClCodes.h templates\authtoken\stAuthTokenApi.cpp inc\authtoken\stAuthTokenApi.h inc\common\stDdaApiDefs.h inc\common\nonwin32\windows.h Add the ASCII C/C++ Runtime Development kit to your system: http://www-919.ibm.com/developer/factory/asciirt/devkit.html 24. Create a library to hold your custom service programs and modules CRTLIB ATHTKNLIB 25. Compile the authentication source files using the following commands: CRTCPPMOD MODULE(ATHTKNLIB/STAUTHTAPI) SRCSTMF('/STToolkit/stAuthTokenApi.cpp') DBGVIEW(*SOURCE) DEFINE('QSRCSTMF' '_UNIX' 'OS400' 'V5R2_COMPILER' 'UNIX_TOOLKIT_COMPILE') TERASPACE(*YES) STGMDL(*INHERIT) INCDIR('/STToolkit' '/qibm/proddata/qadrt/include') TGTCCSID(819)
60
CRTCPPMOD MODULE(ATHTKNLIB/UTILITIES) SRCSTMF('/STToolkit/utilities.cpp') DBGVIEW(*SOURCE) DEFINE('QSRCSTMF' '_UNIX' 'OS400' 'V5R2_COMPILER' 'UNIX_TOOLKIT_COMPILE') TERASPACE(*YES) STGMDL(*INHERIT) INCDIR('/STToolkit' '/qibm/proddata/qadrt/include') TGTCCSID(819) CRTCPPMOD MODULE(ATHTKNLIB/WINPROFILE) SRCSTMF('/STToolkit/winprofile.cpp') DBGVIEW(*SOURCE) DEFINE('QSRCSTMF' '_UNIX' 'OS400' 'V5R2_COMPILER' 'UNIX_TOOLKIT_COMPILE') TERASPACE(*YES) STGMDL(*INHERIT) INCDIR('/STToolkit' '/qibm/proddata/qadrt/include') TGTCCSID(819) 26. Create a service program called STAUTHTKN in library ATHTKNLIB: CRTSRVPGM SRVPGM(ATHTKNLIB/STAUTHTKN) MODULE(ATHTKNLIB/STAUTHTAPI ATHTKNLIB/UTILITIES ATHTKNLIB/WINPROFILE) BNDSRVPGM(QADRTTS) EXPORT(*ALL) OPTION(*DUPVAR *DUPPROC) 27. Change the object owner of the new STAUTHTKN service program to QNOTES: CHGOBJOWN OBJ(ATHTKNLIB/STAUTHTKN) OBJTYPE(*SRVPGM) NEWOWN(QNOTES) To activate this service program on all Sametime servers on your IBM iSeries system: 28. Remove the symbolic link /QIBM/Userdata/lotus/notes/STAUTHTKN.SRVPGM via the CL command: RMVLNK OBJLNK('/qibm/userdata/lotus/notes/STAUTHTKN.SRVPGM'). 29. Create a new link /QIBM/Userdata/lotus/notes/STAUTHTKN.SRVPGM that points to your new STAUTHTKN service program in ATHTKNLIB via the CL command: ADDLNK OBJ('/qsys.lib/ATHTKNLIB.lib/STAUTHTKN.SRVPGM') NEWLNK('/qibm/userdata/lotus/notes/STAUTHTKN.SRVPGM') 30. Change the authority on the new link via the CL command: CHGAUT OBJ('/QIBM/Userdata/lotus/notes/STAUTHTKN.SRVPGM') USER(QNOTES) DTAAUT(*RWX) OBJAUT(*ALL) To activate this service program on a single Sametime server on your IBM iSeries system: 31. Create a new link /yourstserverdatadir/STAUTHTKN.SRVPGM that points to your new STAUTHTKN service program in ATHTKNLIB via the CL command (where yourstserverdatadir is the data directory of the Sametime server on which to deploy the service program): ADDLNK OBJ('/qsys.lib/ATHTKNLIB.lib/STAUTHTKN.SRVPGM') NEWLNK('/yourstserverdatadir/STAUTHTKN.SRVPGM') 32. Change the authority on the new link via the CL command CHGAUT OBJ('/yourstserverdatadir/STAUTHTKN.SRVPGM') USER(QNOTES) DTAAUT(*RWX) OBJAUT(*ALL)
61
To activate the created Token Authentication service program, stop and start the Sametime server(s) on which the service program is installed. For more information stopping and starting Sametime servers, refer to the Sametime 3.1 for iSeries Installation Guide and the Sametime 3.1 Administrators Guide.
Recommendations
When building a Token Authentication DLL or service program, follow the provided template as closely as possible.
62
Token Authentication SPI Reference

This section describes the Token Authentication SPI parameters and the Token Authentication SPI functions.
Token Authentication SPI Parameters

This section contains information about: Token Authentication SPI Return Messages Token Authentication SPI Constants
Token Authentication SPI Return Messages

These return messages are common to all Sametime Toolkit SPIs, APIs, and DLLs, including the Token Authentication SPI.
Return message ST_DDA_API_OK Value 0x0000 Description
Returned by the SPI functions when the requested operation succeeds 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, and so on) 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 token authentication library does not support the SPI version
ST_DDA_API_VERSION_MISMATCH
0x0001
ST_DDA_API_INVALID_PARAM
0x0002
0x0003
0x0004
63
Token Authentication SPI Constants

These constants, defined in stDdaApiDefs.h, are common to all Sametime toolkit SPIs, APIs, and DLLs, including the Token Authentication SPI.
Name ST_DDA_MAX_NAME_LENGTH Value Description
256 characters
This constant defines the maximum length of the login name, user name, and group name. This constant defines the maximum length of a user ID or group ID. This constant defines the maximum length of a user description or a group description string. These constants are used to 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, such as 0x08 or 0x10.
ST_DDA_MAX_ID_LENGTH
256 characters
ST_DDA_MAX_DESCRIPTION_LENGTH
256 characters
ST_DDA_API_NOTES, ST_DDA_API_LDAP
0x0002, 0x0004
respectively
64
Token Authentication SPI Functions

This section describes the Token Authentication SPI functions provided by this toolkit. The Sametime Token Authentication SPI provides the following functions: stTokenInit stTokenTerminate stVerifyToken stGetToken
stTokenInit
Overview The stTokenInit function initializes the Token Authentication SPI module. The syntax for this call is:
int ST_DDA_API
stTokenInit(/*in*/ int initializedOutside,
/*out*/ int* initializedInside )
Description The stTokenInit function initializes the Token Authentication SPI module. Parameters - Input initializedOutside A bit mask describing the platform interfaces initialized by other directory access libraries before the call to this function was made. The values ST_DDA_API_SYBASE, ST_DDA_API_NOTES, and ST_DDA_API_LDAP are predefined. New implementations of the directory access libraries can use other value definitions for other directory/database platforms.
65
Parameters - Output initializedInside A bit mask describing the platform interfaces initialized by this function. It is used by the function in conjunction with the initializedOutside parameter; the function decides what interfaces still need to be initialized based on the value of initializedOutside. It keeps an internal record of the initialized interfaces and sets the initializedInside parameter accordingly.
Return Values
ST_DDA_API_OK ST_DDA_API_INTERNAL_ERROR 0x0000 0x0003
Initialization succeeded Initialization failed
stTokenTerminate
Overview The stTokenTerminate function is called when the process is terminated. It can do the necessary cleanup before the process termination. For example, in the Lotus Notes environment this function can terminate the Notes API. The syntax for this call is:
void ST_DDA_API stTokenTerminate()
Description This function terminates any platform interface initialized by the library. It uses the copy of the value of initializedInside that it saved when stTokenInit was called. Parameters - Input none Parameters - Output none
66
Return Values none
stVerifyToken
Overview The stVerifyToken function attempts to verify the authentication token. The syntax for this call is:
int ST_DDA_API stVerifyToken(/*in*/ const char* loginName,
/*in*/ const char* token,
/*in*/ int tokenLength )
Description This function is called when a user authenticates by token. The stVerifyToken function verifies that the token provided as input is valid, matches the provided login name, and has not expired. If the token is valid, the function returns 0. Parameters Input loginName token tokenLength String containing users login name Pointer to a buffer with the token Denotes the length of the token to be read from the token buffer
67
Return Values
Indicates that the action succeeded. Indicates that the verification failed and, as a result, the user login will fail. The stVerifyToken function tried to verify token but failed.
ST_DDA_AUTH_BAD_LOGIN
0x0002
0x0003
stGetToken
Overview The stGetToken function retrieves the authentication token. The syntax for this call is:
int ST_DDA_API stGetToken(/*in*/ const char* userId,
/*out*/ char* token,
/*out*/ int* tokenLength)
Description The stGetToken function generates a token for the provided user ID. With this token the client can log in at a later time without requiring a password. For example, a client application can send a request to get a token when it re-logs in or launches another client application that must log in to the Sametime server. With the token, the client application can log in without challenging the user for a password. You can make the token valid for only a limited period of time. Parameters - Input UserID The users unique ID in the community,such as the users
particular name in Notes or LDAP
68
Parameters - Output token Pointer to a buffer containing the token generated by the function Pointer to buffer containing the token length
tokenLength Return Values

ST_DDA_API_OK
0x0000 0x0003
Indicates that the action succeeded. The stGetToken function tried to get a token but failed.
69

Same Time Dat K Daev Guide

Caricato da

Informazioni sul documento

Descrizione originale:

Titolo originale

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

Same Time Dat K Daev Guide

Caricato da

Copyright:

Formati disponibili

Lotus Instant Messaging and Web Conferencing

Directory and Database Access Toolkit

Copyright and Trademark Information

Licensed Materials - Property of IBM

For DSIG base64

For MD5 hash

For Log4J Logging

Persistent Data in the Community Server......................................................... 4

Introduction to the Chat Logging SPI................................................................ 7

Architecture................................................................................................................7 Chat Logging Management.......................................................................................8

Getting Started .................................................................................................. 13

Chat Logging SPI Contents ................................................................................... 13

Chat Logging SPI Sample................................................................................. 19

Sametime.ini Flags for the Chat Logging SPI Sample ........................................ 19

Chat Logging SPI Reference ............................................................................ 43

Chat Logging SPI Parameters ............................................................................... 43

Token Authentication SPI .....................................................................57

Token Authentication SPI Contents...................................................................... 58

Building the Token Authentication DLL or Service Program........................ 58

Token Authentication SPI Reference .............................................................. 63

Token Authentication SPI Parameters ................................................................. 63

About This Guide

About This Guide

How to Use this Guide

Chapter 2: Chat Logging SPI

Chapter 3: Token Authentication SPI

About This Guide

Configuration Data Access

Chapter 2 Chat Logging SPI

Chapter 2 Chat Logging SPI

Chat Logging Management

Chapter 2 Chat Logging SPI

Chat Logging in a Distributed Environment

Synchronous and Asynchronous Implementation

Chapter 2 Chat Logging SPI

Chapter 2 Chat Logging SPI

ST_DDA_WARNING ST_DDA_ERROR ST_DDA_FATAL

Chat Logging Effect on the Sametime Server Performance

Chapter 2 Chat Logging SPI

Chapter 2 Chat Logging SPI

Chat Logging SPI Contents

Building the Chat Logging DLL or Service Program

Chapter 2 Chat Logging SPI

Building and Installing a Chat Logging DLL for Windows

Chapter 2 Chat Logging SPI

Chapter 2 Chat Logging SPI

Chapter 2 Chat Logging SPI

Chapter 2 Chat Logging SPI

To prevent information loss, concatenate the messages.

Chapter 2 Chat Logging SPI

Chat Logging SPI Sample

Sametime.ini Flags for the Chat Logging SPI Sample

Chat Logging SPI Sample Parameters

Chat Logging SPI Sample Error Messages

Chapter 2 Chat Logging SPI

Chat Logging SPI Sample Constants

Chapter 2 Chat Logging SPI

Chapter 2 Chat Logging SPI

Chat Logging SPI Sample Code

Chapter 2 Chat Logging SPI

if (*prVersion < ST_DDA_CL_LIB_VERSION)

Chapter 2 Chat Logging SPI