clTmsApi.h

Go to the documentation of this file.

/*
 * Copyright (C) 2002-2012 OpenClovis Solutions Inc.  All Rights Reserved.
 *
 * This file is available  under  a  commercial  license  from  the
 * copyright  holder or the GNU General Public License Version 2.0.
 * 
 * The source code for  this program is not published  or otherwise 
 * divested of  its trade secrets, irrespective  of  what  has been 
 * deposited with the U.S. Copyright office.
 * 
 * This program is distributed in the  hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied  warranty  of 
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 
 * General Public License for more details.
 * 
 * For more  information, see  the file  COPYING provided with this
 * material.
 */
/*******************************************************************************
 * ModuleName  : gms
 * File        : clTmsApi.h
 *******************************************************************************/

/*******************************************************************************
 * Description :
 *
 * This client API extends the SA Forum compliant cluster membership
 * query and tracking API with group view management.
 *
 * Special applications can use this service to create and manage
 * group (views) on top of the cluster (views).
 * 
 *
 * Synchronization of the group with the cluster group view is provided
 * by the implementation of this service and it works as follows: 
 * An application can create a group and join the group if its node is also
 * part of the cluster group. If a cluster node leaves (or is removed) from
 * the cluster, any process on the removed node that participates in any 
 * group(s) is also removed from the respective group(s).
 *
 * An instance of this service (instantiated by the clTmsInitialize()
 * API and identified by the svcHandle) can view and manage any group. 
 *
 *
 * FIXME/TODO:
 * - Need to make sure all error codes are defined (here or in clCommon.h)
 * - Need to address group address synchronization issue.  If this service
 *   is to synchronize group address with group membership, then this has
 *   to be requested explicitely (and the address provided too).
 *  
 *
 *****************************************************************************/

#ifndef _CL_TMS_API_H
#define _CL_TMS_API_H

# ifdef __cplusplus
extern "C" {
# endif

#include <clCommon.h>
#include <clClmApi.h>
#include <clTmsApi.h>

/*=========================================================================
 * Type/constant definitions:
 *=======================================================================*/

#define clTmsInitialize                 clGmsInitialize
#define clTmsFinalize                   clGmsFinalize

typedef ClGmsHandleT                    ClTmsHandleT;
typedef ClGmsGroupNameT                 ClTmsGroupNameT;
typedef ClGmsGroupIdT                   ClTmsGroupIdT;
typedef ClGmsGroupParamsT               ClTmsGroupParamsT;
typedef ClGmsMemberIdT                  ClTmsMemberIdT;
typedef ClGmsMemberNameT                ClTmsMemberNameT;
typedef ClGmsLeadershipCredentialsT     ClTmsLeadershipCredentialsT;
typedef ClGmsGroupNotificationBufferT   ClTmsGroupNotificationBufferT;
typedef ClGmsGroupInfoListT             ClTmsGroupInfoListT;
typedef ClGmsGroupInfoT                 ClTmsGroupInfoT;
typedef ClGmsGroupMemberT               ClTmsGroupMemberT;

/*=========================================================================
 * Callback Functions:
 *=======================================================================*/
typedef void (*ClTmsGroupMessageDeliveryCallbackT) (ClTmsGroupIdT    groupId,
                                                    ClTmsMemberIdT   senderId,
                                                    ClUint32T        messageSize,
                                                    void            *message);


/*=========================================================================
 * API Functions:
 *=======================================================================*/

extern ClRcT clTmsGroupCreate(
        CL_IN    ClTmsHandleT                        svcHandle,
        CL_IN    ClTmsGroupNameT                    *groupName,
        CL_INOUT ClTmsGroupParamsT                  *groupParams,
        CL_OUT   ClTmsGroupIdT                      *groupId);


extern ClRcT clTmsGroupDestroy(
        CL_IN   ClTmsHandleT                    svcHandle,
        CL_IN   ClTmsGroupIdT                   groupId);

extern ClRcT clTmsGroupJoin(
        CL_IN ClTmsHandleT                        svcHandle,
        CL_IN ClTmsGroupIdT                       groupId,
        CL_IN ClTmsMemberIdT                      memberId,
        CL_IN ClTmsMemberNameT                   *memberName,
        CL_IN ClTmsLeadershipCredentialsT         credentials,
        CL_IN ClTmsGroupMessageDeliveryCallbackT  msgDeliveryCallback,
        CL_IN ClTimeT                             timeout);


extern ClRcT clTmsGroupLeave(
        CL_IN ClTmsHandleT                      svcHandle,
        CL_IN ClTmsGroupIdT                     groupId,
        CL_IN ClTmsMemberIdT                    memberId,
        CL_IN ClTimeT                           timeout);

extern ClRcT   clTmsSendAll(
        CL_IN   ClGmsHandleT        svcHandle,
        CL_IN   ClGmsGroupIdT       groupId,
        CL_IN   ClGmsMemberIdT      memberId,
        CL_IN   ClTimeT             timeout,
        CL_IN   ClUint32T           dataSize,
        CL_IN   ClPtrT              data);

extern ClRcT clTmsGroupTrack(
        CL_IN    ClTmsHandleT           svcHandle,
        CL_IN    ClTmsGroupIdT          groupId,
        CL_IN    ClUint8T               trackFlags,
        CL_INOUT ClTmsGroupNotificationBufferT *notificationBuffer);

extern ClRcT clTmsGroupTrackStop(
        CL_IN ClTmsHandleT              svcHandle,
        CL_IN ClTmsGroupIdT             groupId);

extern ClRcT clTmsListGroups(
        CL_IN     ClTmsHandleT             svcHandle,
        CL_IN     ClTimeT                  timeout,
        CL_INOUT  ClTmsGroupInfoListT     *groups);


extern ClRcT clTmsGetGroupInfo(
        CL_IN     ClTmsHandleT             svcHandle,
        CL_IN     ClTmsGroupNameT         *groupName,
        CL_IN     ClTimeT                  timeout,
        CL_INOUT  ClTmsGroupInfoT         *groupInfo);

#ifdef  __cplusplus
}
#endif

#endif  /* _CL_TMS_API_H_ */