Defines, Structures, Typedefs, Functions. More...

Files
file	clClmApi.h
	Header file of SA Forum compliant Group Membership Service.
file	clClmTmsCommon.h
	Header file of Group Membership Service APIs.
file	clGmsErrors.h
	Header file of Error Codes returned by the Group Membership Service.
file	clTmsApi.h
	Header file of Group Membership Service APIs.

Classes
struct	ClGmsCallbacksT
	This callback structure is provided to the GMS library during Initialization. More...
struct	ClGmsClusterManageCallbacksT
	This structure contains the cluster managing callbacks provided at the joining time by the member. More...
struct	ClGmsClusterMemberT
	This structure describes one member (or node) of the cluster. More...
struct	ClGmsClusterNotificationBufferT
	Buffer to convey the view: the list of nodes and their status. More...
struct	ClGmsClusterNotificationT
	Buffer containing the list of nodes that forms the current view of cluster. More...
struct	ClGmsGroupInfoListT
	Structure used to pass the meta data on all the existing groups. More...
struct	ClGmsGroupInfoT
	Structure used to hold the metadata of a group. More...
struct	ClGmsGroupMemberT
	Structure containing attributes of a group member. More...
struct	ClGmsGroupNotificationBufferT
	Buffer to convey the view: the list of group member attributes. More...
struct	ClGmsGroupNotificationT
	Buffer containing the list of group members in the requested view. More...
struct	ClGmsGroupParamsT
	Parameters for group provided during group creation. More...
struct	ClGmsNodeAddressT
	IP Address of the node can be of IPv4 or IPv6. More...

Macros
#define	CL_GMS_ERR_CLUSTER_VERSION_MISMATCH 0x107
	If the joining node is version incompatible with that of the other nodes in the cluster .
#define	CL_GMS_ERR_CONFIG_FILE_INVALID 0x102
	The config file paramer is invalid(NOT used)
#define	CL_GMS_ERR_EMPTY_GROUP 0x104
	The group is empty (INCOMPLETE Usage)
#define	CL_GMS_ERR_GROUP_DOESNT_EXIST 0x103
	Requested group doesnt exist.
#define	CL_GMS_ERR_IOC_DEREGISTRATION 0x106
	IOC Deregistration of the group member failed.
#define	CL_GMS_ERR_IOC_REGISTRATION 0x105
	IOC registration of the group member failed.
#define	CL_GMS_ERR_TOTEM_PROTOCOL_ERROR 0x101
	An error found while performing operation on openais interface.
#define	CL_GMS_ERR_UNMARSHALING_FAILED 0x100
	Unmarshalling RMD Reply failed.
#define	CL_GMS_INELIGIBLE_CREDENTIALS 0x0
	The credential value which will not be considered during leader election.
#define	CL_GMS_INVALID_GROUP_ID -1
	Invalid group ID.
#define	CL_GMS_INVALID_HANDLE ((ClGmsHandleT)0)
	Invalid svc handle.
#define	CL_GMS_INVALID_NODE_ID 0xffffffff
	Indicates the invalid value of the node Id.
#define	CL_GMS_LOCAL_NODE_ID 0XFFFFFFFF
	Indicates the local node.
#define	CL_GMS_MAX_ADDRESS_LENGTH 64
	Maximum length of the address value.
#define	clTmsInitialize clGmsInitialize
	Handle to be associated with each group.
#define	LEADER_ELECTION_ALGORITHM "LeaderElectionAlgorithm"
	Name of the Function to be defined in the Leader Election algorithm plugin.

Typedefs
typedef struct ClGmsCallbacksT	ClGmsCallbacksT
	This callback structure is provided to the GMS library during Initialization.
typedef enum ClGmsClusterChangesT	ClGmsClusterChangesT
	Enumerator and structure for the node status notification for tracking nodes.
typedef void(*	ClGmsClusterMemberEjectCallbackT )(CL_IN ClGmsMemberEjectReasonT reasonCode)
	Callback for indicating that member was expelled from the cluster.
typedef void(*	ClGmsClusterMemberGetCallbackT )(CL_IN ClInvocationT invocation, CL_IN const ClGmsClusterMemberT *clusterMember, CL_IN ClRcT rc)
	Callback for asynchronous cluster member query.
typedef void(*	ClGmsClusterTrackCallbackT )(CL_IN const ClGmsClusterNotificationBufferT *notificationBuffer, CL_IN ClUint32T numberOfMembers, CL_IN ClRcT rc)
	Callback for tracking cluster view changes.
typedef enum ClGmsGroupChangesT	ClGmsGroupChangesT
	Enumerator and structure of member status notification.
typedef ClUint32T	ClGmsGroupIdT
	System-wide unique ID of the group.
typedef struct ClGmsGroupInfoListT	ClGmsGroupInfoListT
	Structure used to pass the meta data on all the existing groups.
typedef struct ClGmsGroupInfoT	ClGmsGroupInfoT
	Structure used to hold the metadata of a group.
typedef void(*	ClGmsGroupMemberGetCallbackT )(CL_IN ClInvocationT invocation, CL_IN const ClGmsGroupMemberT *groupMember, CL_IN ClRcT rc)
	Callback for asynchronous group member query.
typedef ClNameT	ClGmsGroupNameT
	System-wide unique name of the group.
typedef struct ClGmsGroupNotificationT	ClGmsGroupNotificationT
	Buffer containing the list of group members in the requested view.
typedef struct ClGmsGroupParamsT	ClGmsGroupParamsT
	Parameters for group provided during group creation.
typedef void(*	ClGmsGroupTrackCallbackT )(CL_IN ClGmsGroupIdT groupId, CL_IN const ClGmsGroupNotificationBufferT *notificationBuffer, CL_IN ClUint32T numberOfMembers, CL_IN ClRcT rc)
	Callback for tracking group view changes.
typedef ClHandleT	ClGmsHandleT
	Handle for using the GMS API.
typedef ClRcT(*	ClGmsLeaderElectionAlgorithmT )(ClGmsClusterNotificationBufferT buffer, ClGmsNodeIdT leaderNodeId, ClGmsNodeIdT deputyNodeId, ClGmsClusterMemberT *memberJoinedOrLeft, ClGmsGroupChangesT cond)
	Signature of the leader election algorithm used in the GMS engine .
typedef ClUint32T	ClGmsLeadershipCredentialsT
	Credentials for leader election.
typedef ClUint32T	ClGmsMemberIdT
	Group-unique ID of a member.
typedef ClNameT	ClGmsMemberNameT
	Group-unique name of the member.
typedef enum ClGmsNodeAddressFamilyT	ClGmsNodeAddressFamilyT
	This type defines the family to which the address of the node belongs.
typedef struct ClGmsNodeAddressT	ClGmsNodeAddressT
	IP Address of the node can be of IPv4 or IPv6.
typedef ClUint32T	ClGmsNodeIdT
	Node ID – Unique and consistent identifier of a node.
typedef enum ClGmsTrackFlagsT	ClGmsTrackFlagsT
	Flags for tracking request flag.

Enumerations
enum	ClGmsClusterChangesT { CL_GMS_NODE_NO_CHANGE = 1, CL_GMS_NODE_JOINED = 2, CL_GMS_NODE_LEFT = 3, CL_GMS_NODE_RECONFIGURED = 4 }
	Enumerator and structure for the node status notification for tracking nodes. More...
enum	ClGmsGroupChangesT { CL_GMS_MEMBER_NO_CHANGE = 1, CL_GMS_MEMBER_JOINED = 2, CL_GMS_MEMBER_LEFT = 3, CL_GMS_MEMBER_RECONFIGURED = 4, CL_GMS_LEADER_ELECT_API_REQUEST = 5 }
	Enumerator and structure of member status notification. More...
enum	ClGmsMemberEjectReasonT { CL_GMS_MEMBER_EJECT_REASON_UNKNOWN = 0, CL_GMS_MEMBER_EJECT_REASON_API_REQUEST = 1 }
	Reason codes for ejecting the user from cluster/group. More...
enum	ClGmsNodeAddressFamilyT { CL_GMS_AF_INET = 1, CL_GMS_AF_INET6 = 2 }
	This type defines the family to which the address of the node belongs. More...
enum	ClGmsTrackFlagsT { CL_GMS_TRACK_CURRENT = 0x01, CL_GMS_TRACK_CHANGES = 0x02, CL_GMS_TRACK_CHANGES_ONLY = 0x04 }
	Flags for tracking request flag. More...

Functions
struct ClGmsClusterMemberT	__attribute__ ((__aligned__(8)))
	This structure describes one member (or node) of the cluster.
ClRcT	clGmsClusterLeaderElect (CL_IN ClGmsHandleT gmsHandle, CL_IN ClGmsNodeIdT preferredLeader, CL_INOUT ClGmsNodeIdT leader, CL_INOUT ClGmsNodeIdT deputy, CL_INOUT ClBoolT *leadershipChanged)
	Initiate leader election synchronously.
ClRcT	clGmsClusterMemberEject (CL_IN ClGmsHandleT gmsHandle, CL_IN ClGmsNodeIdT nodeId, CL_IN ClGmsMemberEjectReasonT reason)
	Forcibly removes a member from the cluster.
ClRcT	clGmsClusterMemberGet (CL_IN ClGmsHandleT gmsHandle, CL_IN ClGmsNodeIdT nodeId, CL_IN ClTimeT timeout, CL_OUT ClGmsClusterMemberT *clusterMember)
	Returns cluster member information.
ClRcT	clGmsClusterMemberGetAsync (CL_IN ClGmsHandleT gmsHandle, CL_IN ClInvocationT invocation, CL_IN ClGmsNodeIdT nodeId)
	Returns information on the cluster node asynchronously.
ClRcT	clGmsClusterTrack (CL_IN ClGmsHandleT gmsHandle, CL_IN ClUint8T trackFlags, CL_INOUT ClGmsClusterNotificationBufferT *notificationBuffer)
	Configures the cluster tracking mode.
ClRcT	clGmsClusterTrackStop (CL_IN ClGmsHandleT gmsHandle)
	Stops all the clusters tracking.
ClRcT	clGmsDispatch (ClGmsHandleT clmHandle, ClDispatchFlagsT dispatchFlags)
	Dispatch API as per SAF symantics for dispatching the pending callbacks.
ClRcT	clGmsFinalize (CL_IN ClGmsHandleT gmsHandle)
	Cleans up the GMS library.
ClRcT	clGmsInitialize (CL_OUT ClGmsHandleT gmsHandle, CL_IN const ClGmsCallbacksT gmsCallbacks, CL_INOUT ClVersionT *version)
	Initializes the GMS library and registers the callback functions.
ClRcT	clGmsSelectionObjectGet (ClGmsHandleT clmHandle, ClSelectionObjectT *pSelectionObject)
	The selection object fd provided by GMS client on which the user can poll for any callbacks as per SAF symantics.
ClRcT	clTmsGetGroupInfo (CL_IN ClTmsHandleT svcHandle, CL_IN ClTmsGroupNameT groupName, CL_IN ClTimeT timeout, CL_INOUT ClTmsGroupInfoT groupInfo)
	Returns the information of a group specified by the groupName.
ClRcT	clTmsGroupCreate (CL_IN ClTmsHandleT svcHandle, CL_IN ClTmsGroupNameT groupName, CL_INOUT ClTmsGroupParamsT groupParams, CL_OUT ClTmsGroupIdT *groupId)
	Create a group.
ClRcT	clTmsGroupDestroy (CL_IN ClTmsHandleT svcHandle, CL_IN ClTmsGroupIdT groupId)
	Destroy a group.
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)
	Join the group as a member.
ClRcT	clTmsGroupLeave (CL_IN ClTmsHandleT svcHandle, CL_IN ClTmsGroupIdT groupId, CL_IN ClTmsMemberIdT memberId, CL_IN ClTimeT timeout)
	Leave the group.
ClRcT	clTmsGroupTrack (CL_IN ClTmsHandleT svcHandle, CL_IN ClTmsGroupIdT groupId, CL_IN ClUint8T trackFlags, CL_INOUT ClTmsGroupNotificationBufferT *notificationBuffer)
	Configures the group tracking mode.
ClRcT	clTmsGroupTrackStop (CL_IN ClTmsHandleT svcHandle, CL_IN ClTmsGroupIdT groupId)
	Stops all the group tracking.
ClRcT	clTmsListGroups (CL_IN ClTmsHandleT svcHandle, CL_IN ClTimeT timeout, CL_INOUT ClTmsGroupInfoListT *groups)
	Returns the information on all the groups.
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)
	Send a Totally ordered multicast messages to all members of a given group.

Detailed Description

Defines, Structures, Typedefs, Functions.

Typedef Documentation

typedef enum ClGmsClusterChangesT ClGmsClusterChangesT

Enumerator and structure for the node status notification for tracking nodes.

Each time a node joines or leaves or reconfigured.

typedef void(* ClGmsClusterMemberEjectCallbackT)(CL_IN ClGmsMemberEjectReasonT reasonCode)

Callback for indicating that member was expelled from the cluster.

Header File:: clGmsApi.h

Parameters

reasonCode

(in) Indicates the reason for expelling the node from the cluster. The reasonCodes defined as of now are -

CL_GMS_MEMBER_EJECT_REASON_UNKNOWN = 0
CL_GMS_MEMBER_EJECT_REASON_API_REQUEST =1

Return values

none

Description:: This ClGmsClusterMemberEjectCallback callback function is getting called when a cluster member is ejected by an administrative operation.

Library File:: ClGms

See Also: none

typedef void(* ClGmsClusterMemberGetCallbackT)(CL_IN ClInvocationT invocation, CL_IN const ClGmsClusterMemberT *clusterMember, CL_IN ClRcT rc)

Callback for asynchronous cluster member query.

Header File:: clClmTmsCommon.h

Parameters

invocation	(in) Callback correlator
clusterMember	(in) Buffer containing the node information
rc	(in) Return code from the server

Return values

none

Description:: This ClGmsClusterMemberGetCallbackT callback function is invoked when an async request was made to get the given node information by using clGmsClusterMemberGetAsync() API. The requested member node information is provided in the clusterMember parameter.

Library File:: ClGms

See Also: clGmsClusterMemberGet(), clGmsClusterMemberGetAsync()

typedef void(* ClGmsClusterTrackCallbackT)(CL_IN const ClGmsClusterNotificationBufferT *notificationBuffer, CL_IN ClUint32T numberOfMembers, CL_IN ClRcT rc)

Callback for tracking cluster view changes.

Header File:: clClmTmsCommon.h

Parameters

notificationBuffer	(in) Buffer containing the node information of the cluster
numberOfMembers	(in) Represent the number of nodes' information present in the notification buffer.
rc	(in) Return code from the server

Return values

none

Description:

This ClGmsClusterTrackCallbackT callback function is invoked in following 2 cases:

If the user is registered for cluster track changes with CL_TRACK_CHANGES or CL_TRACK_CHANGES_ONLY track flags, then the callback is invoked for every change in the cluster.
If the user has invoked clGmsClusterTrack API with CL_TRACK_CURRENT flag and the notification buffer is NULL, then the response is served through an invocation of this callback.

Library File:: ClGms

See Also: clGmsInitialize(), clGmsClusterTrack()

typedef void(* ClGmsGroupMemberGetCallbackT)(CL_IN ClInvocationT invocation, CL_IN const ClGmsGroupMemberT *groupMember, CL_IN ClRcT rc)

Callback for asynchronous group member query.

Header File:: clClmTmsCommon.h

Parameters

invocation	(in) Callback correlator
groupMember	(in) Buffer containing the member information
rc	(in) Return code from the server

Return values

none

Description:: This ClGmsGroupMemberGetCallbackT callback function is invoked when an async request was made to get the given member information by using clGmsGroupMemberGetAsync() API. The requested member node information is provided in the clusterMember parameter.

Library File:: ClGms

See Also: clGmsClusterMemberGet(), clGmsClusterMemberGetAsync()

typedef struct ClGmsGroupParamsT ClGmsGroupParamsT

Parameters for group provided during group creation.

Currently no paramters are provided. isIocGroup parameter specifies if the group needs to create IOC multicast address. Please note that non-ioc groups are not supported in release 3.0. So this is for future usage.

typedef void(* ClGmsGroupTrackCallbackT)(CL_IN ClGmsGroupIdT groupId, CL_IN const ClGmsGroupNotificationBufferT *notificationBuffer, CL_IN ClUint32T numberOfMembers, CL_IN ClRcT rc)

Callback for tracking group view changes.

Header File:: clClmTmsCommon.h

Parameters

groupId	(in) Group ID of the group for which the track request is being served.
notificationBuffer	(in) Buffer containing the member information of the group
numberOfMembers	(in) Represent the number of members' information present in the notification buffer.
rc	(in) Return code from the server

Return values

none

Description:

This ClGmsGroupTrackCallbackT callback function is invoked in following 2 cases:

If the user is registered for group track changes with CL_TRACK_CHANGES or CL_TRACK_CHANGES_ONLY track flags, then the callback is invoked for every change in the group.
If the user has invoked clGmsGroupTrack API with CL_TRACK_CURRENT flag and the notification buffer is NULL, then the response is served through an invocation of this callback.

Library File:: ClGms

See Also: clGmsInitialize(), clGmsGroupTrack()

typedef ClHandleT ClGmsHandleT

Handle for using the GMS API.

A handle of this type is assigned during the initialization of the Group Membership Service, and it designates this particular initialization. It must be passed as first parameter for all operations pertaining to the GMS library.

typedef ClRcT(* ClGmsLeaderElectionAlgorithmT)(ClGmsClusterNotificationBufferT buffer, ClGmsNodeIdT *leaderNodeId, ClGmsNodeIdT *deputyNodeId, ClGmsClusterMemberT *memberJoinedOrLeft, ClGmsGroupChangesT cond)

Signature of the leader election algorithm used in the GMS engine .

Leader election algorithm is implemented as plugin (dynamically loadable shared object). Leader election algorithm is invoked upon any changes in the cluster ( member joining or member leaving ) or upon the invocation of the clGmsClusterLeaderElect function. Algorithm is given information regarding The current view of the cluster and the condition in which the algorithm is invoked. Condition can be CL_GMS_MEMBER_JOIN or CL_GMS_MEMBER_LEFT and the pointer to the node is passed to the algorithm.

typedef ClUint32T ClGmsLeadershipCredentialsT

Credentials for leader election.

Only members with the highest value in the group will be considered as candidates for leadership.

Enumeration Type Documentation

enum ClGmsClusterChangesT

Enumerator and structure for the node status notification for tracking nodes.

Each time a node joines or leaves or reconfigured.

Enumerator:

CL_GMS_NODE_NO_CHANGE	No change occured on the node since the last view.
CL_GMS_NODE_JOINED	Node has joined since last view.
CL_GMS_NODE_LEFT	Node has left since last view.
CL_GMS_NODE_RECONFIGURED	Node hes been re-configured since last view.

enum ClGmsGroupChangesT

Enumerator and structure of member status notification.

Enumerator:

CL_GMS_MEMBER_NO_CHANGE	Member unchanged since last view.
CL_GMS_MEMBER_JOINED	Member joined since last view.
CL_GMS_MEMBER_LEFT	Member has left since last view.
CL_GMS_MEMBER_RECONFIGURED	Member reconfigured since last view.
CL_GMS_LEADER_ELECT_API_REQUEST	Leadership election through API.

enum ClGmsMemberEjectReasonT

Reason codes for ejecting the user from cluster/group.

Enumerator:

CL_GMS_MEMBER_EJECT_REASON_UNKNOWN	Reason for the eject not known.
CL_GMS_MEMBER_EJECT_REASON_API_REQUEST	The member has been ejected due to an explicit invocation of clGmsClusterMemberEject() API.

enum ClGmsNodeAddressFamilyT

This type defines the family to which the address of the node belongs.

Enumerator:

CL_GMS_AF_INET	CL_GMS_AF_INET stands for IPv4 address.
CL_GMS_AF_INET6	CL_GMS_AF_INET6 stands for IPv6 address.

enum ClGmsTrackFlagsT

Flags for tracking request flag.

Enumerator:

CL_GMS_TRACK_CURRENT	Returns current view.
CL_GMS_TRACK_CHANGES	To subscribe for view notifications that includes current view and the recent change.
CL_GMS_TRACK_CHANGES_ONLY	To subscribe for delta notifications.

Function Documentation

ClUint64T viewNumber __attribute__ ( (__aligned__(8)) )

This structure describes one member (or node) of the cluster.

Buffer to convey the view: the list of group member attributes.

Credentials for being the leader.

The view number of the group at the time the member joined.

The instant at which the member joined the group.

True if the node is a member of group.

Textual name of the member.

IOC Address of the group member application.

Group-unique ID of the member.

SVC handle of this group member.

Structure containing attributes of a group member.

Current view number.

Buffer to convey the view: the list of nodes and their status.

Node profile as described in the datatype ClGmsClusterMemberT.

Buffer containing the list of nodes that forms the current view of cluster.

Version information of the GMS software running on the node, information is sent to the other peers in the cluster while joining the cluster .

Indicates that the leadership preference is set through CLI and not through config file.

Indicates if this node is the preferred leader for the cluster.

Indicates if this node is the current leader of the cluster or not.

This is an integer value specifying the leadership credibility of the node.

The view number when the node joined.

The time at which GMS was started on the node.

This is TRUE if the node is a member of the cluster For tracking nodes it is not set.

Textual name of node.

Node IP Address.

Physical IOC address of node.

Unique ID of node.

Larger the value higher is the possibility of the node becoming a leader. Member with creditials CL_GMS_INELIGIBLE_CREDENTIALS cannot participate in the leader election This provides higher preference during leader election.

If there is a version mismatch the node is not allowed to join the Cluster

The higher the credential, larger is the possibility of the node being elected as leader.

ClRcT clGmsClusterLeaderElect	(	CL_IN ClGmsHandleT	gmsHandle,
		CL_IN ClGmsNodeIdT	preferredLeader,
		CL_INOUT ClGmsNodeIdT *	leader,
		CL_INOUT ClGmsNodeIdT *	deputy,
		CL_INOUT ClBoolT *	leadershipChanged
	)

Initiate leader election synchronously.

Header File:: clGmsApi.h

Parameters

gmsHandle The handle, obtained through the clGmsInitialize() function, designating this particular initialization of the Group Membership Service

Return values

CL_ERR_INVALID_HANDLE If the handle passed to the function is not valid. The handle passed should have been obtained from the clGmsInitialize() function.

Description:: This function is used to initiate leader election synchronously. The elected leader is announced via the tracking callback. Typically it is invoked when a node leaves or joins, or on any event which would alter the leadership of the cluster. The algorithm will be run by the GMS server engine, and a leader and deputy leader are elected. Here the API runs synchronously means that the election is done as part of the API processing itself. However the results are given through a cluster track callback.

Library File:: ClGms

ClRcT clGmsClusterMemberEject	(	CL_IN ClGmsHandleT	gmsHandle,
		CL_IN ClGmsNodeIdT	nodeId,
		CL_IN ClGmsMemberEjectReasonT	reason
	)

Forcibly removes a member from the cluster.

Header File:: clGmsApi.h

Parameters

gmsHandle	The handle, obtained through the clGmsInitialize() function, designating this particular initialization of the Group Membership Service
nodeId	Node ID of the member to be ejected out.
reason	Reason for ejecting the member out of the cluster. A member can be ejected from the cluster either upon request, or for an unknown reason. reasonCode can have 2 values. CL_GMS_MEMBER_EJECT_REASON_UNKNOWN = 0 CL_GMS_MEMBER_EJECT_REASON_API_REQUEST =1.

Return values

CL_ERR_INVALID_HANDLE	If the handle passed to the function is not valid. The handle passed should have been obtained from the clGmsInitialize() function.
CL_ERR_INVALID_PARAMETER	If the node ID is not a valid node ID or if the reason is not valid.

Description:: This function is used to remove a member forcibly from the cluster. All the process groups or group members if any on the node are expelled from their respective process groups and a reason is given for ejecting them out. The tracking members of the cluster are notified through the tracking callback.

Library File:: ClGms

See Also: clGmsClusterLeaveAsync(), clGmsClusterLeaderElect()

ClRcT clGmsClusterMemberGet	(	CL_IN ClGmsHandleT	gmsHandle,
		CL_IN ClGmsNodeIdT	nodeId,
		CL_IN ClTimeT	timeout,
		CL_OUT ClGmsClusterMemberT *	clusterMember
	)

Returns cluster member information.

Header File:: clClmTmsCommon.h

Parameters

gmsHandle	The handle, obtained through the clGmsInitialize() function, designating this particular initialization of the Group Membership Service.
nodeId	The identifier of the cluster node for which the clusterNode information structure is to be retrieved.
timeout	The clGmsClusterMemberGet() invocation is considered to have failed if it does not complete by the time specified through this parameter.
clusterMember	(out) A pointer to a cluster node structure that contains information about a cluster node. The invoking process provides space for this structure, and the Group Membership Service fills in the fields of this structure.

Return values

CL_OK	The API executed successfully.
CL_ERR_INVALID_HANDLE	On passing an invalid handle.
CL_ERR_NULL_POINTER	If the parameter clusterMember passed is a NULL pointer.
CL_ERR_TIMEOUT	Communication request timed out.
CL_ERR_INVALID_PARAM	Requested node does not exist

Description:: This API is used to retrieve the information on a given cluster member and check whether the node is a member of the cluster. The space for the node must be allocated by you. This function provides the means for synchronously retrieving information about a cluster member, identified by the nodeId parameter. The cluster node information is returned in the clusterNode parameter.

By invoking this function, a process can obtain the cluster node information for the node, designated by nodeId, and can then check the member field to determine whether this node is a member of the cluster. If the constant CL_GMS_LOCAL_NODE_ID is used as nodeId, the function returns information about the cluster node that hosts the invoking process.

Library File:: libClGms

See Also: clGmsClusterTrack(), clGmsClusterTrackStop(), clGmsClusterMemberGetAsync()

ClRcT clGmsClusterMemberGetAsync	(	CL_IN ClGmsHandleT	gmsHandle,
		CL_IN ClInvocationT	invocation,
		CL_IN ClGmsNodeIdT	nodeId
	)

Returns information on the cluster node asynchronously.

Header File:: clClmTmsCommon.h

Parameters

gmsHandle	The handle, obtained through the clGmsInitialize() function, designating this particular initialization of the Group Membership Service.
invocation	Correlates the invocation with the corresponding callback. This parameter allows the invoking process to match this invocation of clGmsClusterMemberGetAsync() with the corresponding clGmsClusterMemberGetCallback().
nodeId	The identifier of the cluster node for which the information is to be retrieved.

Return values

CL_OK	The API executed successfully.
CL_ERR_INVALID_HANDLE	On passing an invalid handle.
CL_GMS_ERR_NODE_DOES_NOT_EXIST	If the requested node does not exist.

Description:: This API is used to query the information on a given cluster node. It makes an asynchronous call to ClGmsClusterMemberGetCallbackT(). This function requests information, to be provided asynchronously, about the particular cluster node, identified by the nodeId parameter. If CL_GMS_LOCAL_NODE_ID is used as nodeId, the function returns information about the cluster node that hosts the invoking process.

The process sets invocation, which it uses subsequently to match the corresponding callback, clGmsClusterMemberGetCallback(), with this particular invocation. The clGmsClusterMemberGetCallback() callback function must have been supplied when the process invoked the clGmsInitialize() call.

Library File:: libClGms

See Also: clGmsClusterTrack(), clGmsClusterTrackStop(), clGmsClusterMemberGet()

ClRcT clGmsClusterTrack	(	CL_IN ClGmsHandleT	gmsHandle,
		CL_IN ClUint8T	trackFlags,
		CL_INOUT ClGmsClusterNotificationBufferT *	notificationBuffer
	)

Configures the cluster tracking mode.

Header File:: clClmTmsCommon.h

Parameters

gmsHandle	The handle, obtained through the clGmsInitialize() function, designating this particular initialization of the Group Membership Service.
trackFlags	Requested tracking mode.
notificationBuffer	(in/out) Notification buffer provided by you while making a request for the `CURRENT` view. This is an optional parameter.

Return values

CL_OK	The API executed successfully.
CL_ERR_INVALID_HANDLE	On passing an invalid handle.
CL_ERR_INVALID_PARAMETER	If `CL_GMS_TRACK_CURRENT` flag is set and notification buffer is provided, but size of allocated array is not set (0).
CL_GMS_ERR_INVALID_TRACKFLAGS	If both `CHANGES` and `CHANGES_ONLY` flags are set.
CL_ERR_NO_CALLBACK	If request was asynchronous but no callback was registered.
CL_ERR_TRY_AGAIN	Communication error, try again.
CL_ERR_TIMEOUT	Communication request timed out.

Description:: This API is used to configure the cluster tracking mode for the caller. It can be called subsequently to modify the requested tracking mode. This function is used to obtain the current cluster membership as well as to request notification of changes in the cluster membership or of changes in an attribute of a cluster node, depending on the value of the trackFlags parameter.

These changes are notified via the invocation of the clGmsClusterTrackCallback() callback function, which must have been supplied when the process invoked the clGmsInitialize() call. An application may call clGmsClusterTrack() repeatedly for the same values of gmsHandle, regardless of whether the call initiates a one-time status request or a series of callback notifications.

Library File:: libClGms

See Also: clGmsClusterTrackStop(), clGmsClusterMemberGet(), clGmsClusterMemberGetAsync()

ClRcT clGmsClusterTrackStop ( CL_IN ClGmsHandleT gmsHandle )

Stops all the clusters tracking.

Header File:: clClmTmsCommon.h

Parameters

gmsHandle The handle, obtained through the clGmsInitialize() function, designating this particular initialization of the Group Membership Service.

Return values

CL_OK	The API executed successfully.
CL_ERR_INVALID_HANDLE	On passing an invalid handle.

Description:: This API is used to immediately stop the tracking of all the clusters for a given client. This function stops any further notifications through the handle gmsHandle. Pending callbacks are removed. This is usually invoked during the shut-down of the application.

Library File:: libClGms

See Also: clGmsClusterTrack(), clGmsClusterMemberGet(), clGmsClusterMemberGetAsync()

ClRcT clGmsDispatch	(	ClGmsHandleT	clmHandle,
		ClDispatchFlagsT	dispatchFlags
	)

Dispatch API as per SAF symantics for dispatching the pending callbacks.

Parameters

clmHandle	GMS client handle obtained from clGmsInitialize
dispatchFlags	Dispatch flags as per SAF symantics

ClRcT clGmsFinalize ( CL_IN ClGmsHandleT gmsHandle )

Cleans up the GMS library.

Header File:: clClmTmsCommon.h

Parameters

gmsHandle The handle, obtained through the clGmsInitialize() function, designating this particular initialization of the Group Membership Service.

Return values

CL_OK	The API executed successfully.
CL_ERR_INVALID_HANDLE	On passing an invalid handle.

Description:: The clGmsFinalize() function closes the association, represented by the gmsHandle parameter, between the invoking process and the Group Membership Service. The process must have invoked clGmsInitialize() before it invokes this function. A process must invoke this function once for each handle it acquired by invoking clGmsInitialize().

If the clGmsInitialize() function returns successfully, the clGmsFinalize() function releases all resources acquired when clGmsInitialize() was called. Moreover, it stops any tracking associated with the particular handle. Furthermore, it cancels all pending callbacks related to the particular handle. Note that because the callback invocation is asynchronous, it is still possible that some callback calls are processed after this call returns successfully. After clGmsFinalize() is invoked, the selection object is no longer valid.

Note: On successful execution of this function, it releases all the resources allocated during the initialization of the library.

Library File:: libClGms

See Also: clGmsInitialize()

ClRcT clGmsInitialize	(	CL_OUT ClGmsHandleT *	gmsHandle,
		CL_IN const ClGmsCallbacksT *	gmsCallbacks,
		CL_INOUT ClVersionT *	version
	)

Initializes the GMS library and registers the callback functions.

Header File:: clClmTmsCommon.h

Parameters

gmsHandle	(out) GMS service handle created by the library. This is used in subsequent use of the library in this session.
gmsCallbacks	Pointer to the array of callback functions provided If gmsCallbacks is set to NULL, no callback is registered; otherwise, it is a pointer to a clGmsCallbacksT structure, containing the callback functions of the process that the Group Membership Service may invoke. Only non-NULL callback functions in this structure will be registered. This is an optional parameter.
version	(in/out) It can have the following values: On input, this is the version desired by you. On return, the library returns the version it supports.

Return values

CL_OK	The API executed successfully.
CL_ERR_NOT_INITIALIZED	If library was not initialized.
CL_ERR_NULL_POINTER	On passing a NULL pointer.
CL_ERR_VERSION_MISMATCH	If the requested version is not compatible with the ASP library.
CL_ERR_NO_RESOURCE	If an instance or a new handle cannot be created.

Description:: This function initializes the Group Membership Service (GMS) for the invoking process and registers the various callback functions and negotiates the version of GMS library being used. This function must be invoked prior to the invocation of any other Group Membership Service functionality. The handle gmsHandle is returned as the reference to this association between the process and the Group Membership Service. The process uses this handle in subsequent communication with the GMS.

Library File:: libClGms

See Also: clGmsFinalize()

ClRcT clGmsSelectionObjectGet	(	ClGmsHandleT	clmHandle,
		ClSelectionObjectT *	pSelectionObject
	)

The selection object fd provided by GMS client on which the user can poll for any callbacks as per SAF symantics.

Parameters

clmHandle	GMS Handle obtained from clGmsInitialize
pSelectionObject	Address of selection object element which will be filled by gms client

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

Returns the information of a group specified by the groupName.

Header File:: clTmsApi.h

Parameters

svcHandle	Handle of the GMS service session.
groupName	Pointer to ClGmsGroupNameT structure holding the value and length for the name of the group for which info is requested.
timeout	Max timeout value for the API.
groupInfo	Pointer to ClGmsGroupInfoT structure. User has to allocate memory for the ClGmsGroupInfoT structure and pass the address of the memory location throught groupInfo pointer. GMS will fill-in the values in the memory pointed by groupInfo

Return values

CL_ERR_INVALID_HANDLE	On passing an invalid handle.
CL_ERR_NULL_POINTER	groupName or groupInfo pointers are NULL
CL_ERR_TIMEOUT	Operation Timed out.
CL_ERR_DOESNT_EXIST	Group indicated by the groupName doesnt exist.
CL_ERR_TRY_AGAIN	Server is not ready to serve the request.

Description:: This API is used to retrieve the information on a given group member. The space for the member node must be allocated by you.

Library File:: libClGms

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

Create a group.

Parameters

svcHandle	svcHandle provided during clTmsInitialize
groupName	Name of the group. Specify the value and length
groupId	Pointer to the memory to store groupId generated by GMS.
groupParams	Includes parameters such as isIocGroup etc. By default all the groups are Ioc Groups.

Return values

CL_ERR_TRY_AGAIN	Server is not ready to serve group functionality
CL_ERR_VERSION_MISMATCH	Client version not supported
CL_ERR_INVALID_HANDLE	svcHandle is invalid
CL_ERR_NULL_POINTER	groupName or groupId params are NULL
CL_ERR_NO_MEMORY	Could not allocate memory to create groups.
CL_ERR_NO_RESOURCE	Could not allocate resource to create groups.
CL_ERR_ALREADY_EXIST	Group is already created. At this point the created groupId is returned in groupId parameter.
CL_ERR_TIMEOUT	Group Creation timeout.
CL_ERR_UNSPECIFIED	Group creation failed with unknown error.

Description:: Create a group. User needs to pass groupName and groupId pointer. GMS will generate a groupId which will be unique across the cluster, and it will be returned through groupId pointer.

ClRcT clTmsGroupDestroy	(	CL_IN ClTmsHandleT	svcHandle,
		CL_IN ClTmsGroupIdT	groupId
	)

Destroy a group.

Parameters

svcHandle	svcHandle provided during gmsInitialize.
groupId	groupId provided during GroupCreate

Return values

CL_ERR_TRY_AGAIN	Server is not ready to serve group functionality
CL_ERR_VERSION_MISMATCH	Client version not supported
CL_ERR_INVALID_HANDLE	svcHandle is invalid
CL_ERR_DOESNT_EXIST	Requested group with groupId doesnt exist.
CL_ERR_INUSE	Group is not empty. However in this case, the group will be set inActive and hence no further joins can happen.

Description:: Destroy a group. The group will be destroyed on all nodes across the cluster.

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
	)

Join the group as a member.

Parameters

svcHandle	svcHandle provided during clTmsInitialize
groupId	groupId provided during group creation.
memberId	Id of the member joining the group.
memberName	Name of the memebr joining the group. This is optional
credentials	Leadership credentials of the group member [Currently not used]
timeout	Join timeout

Return values

CL_ERR_TRY_AGAIN	Server is not ready to serve group functionality
CL_ERR_VERSION_MISMATCH	Client version not supported
CL_ERR_INVALID_HANDLE	svcHandle is invalid
CL_ERR_TIMEOUT	Groupjoin timeout
CL_ERR_DOESNT_EXIST	requested group does not exist.
CL_ERR_NULL_POINTER	memberName is not provided.
CL_ERR_ALREADY_EXIST	The application is an existing member of the group.
CL_ERR_INVALID_OPERATION	Join is denied as the group is marked to be destroyed.

Description:: Join the group as a member. Success is reported to caller via return value. Others get notified by tracking callback.

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

Leave the group.

Parameters

svcHandle	svcHandle provided during clTmsInitialize
groupId	groupId provided during group creation.
memberId	Id of the member Leaving the group.
timeout	Leave timeout

Return values

CL_ERR_TRY_AGAIN	Server is not ready to serve group functionality
CL_ERR_VERSION_MISMATCH	Client version not supported
CL_ERR_INVALID_HANDLE	svcHandle is invalid
CL_ERR_TIMEOUT	GroupLeave timeout
CL_ERR_DOESNT_EXIST	requested memberId does not exist.
CL_ERR_GROUP_DOESNT_EXIST	requested group does not exist.

Description:: Leave the group. Success is retured to caller via return value. Others will be notified through track callback.

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

Configures the group tracking mode.

Header File:: clTmsApi.h

Parameters

svcHandle	Handle of the GMS service session.
groupId	Id of the group.
trackFlags	Requested tracking mode.
notificationBuffer	Notification buffer provided by you while making a request for the `CURRENT` view. This is an optional parameter.

Return values

CL_ERR_INVALID_HANDLE	On passing an invalid handle.
CL_GMS_ERR_GROUP_DOES_NOT_EXIST	If the requested group does not exist.
CL_ERR_INVALID_PARAMETER	On passing an invalid parameter.
CL_ERR_NULL_POINTER	On passing a NULL pointer.

Description:: This API is used to configure the group tracking mode for a given group. It can be called subsequently to modify the requested tracking mode.

ClRcT clTmsGroupTrackStop	(	CL_IN ClTmsHandleT	svcHandle,
		CL_IN ClTmsGroupIdT	groupId
	)

Stops all the group tracking.

Header File:: clTmsApi.h

Parameters

svcHandle	Handle of the GMS service session.
groupId	Id of the group.

Return values

CL_ERR_INVALID_HANDLE	On passing an invalid handle.
CL_GMS_ERR_GROUP_DOES_NOT_EXIST	If the requested group does not exist.

Description:: This API is used to immediately stop all the group tracking for a group.

Library File:: libClGms

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

Returns the information on all the groups.

Header File:: clTmsApi.h

Parameters

svcHandle	Handle of the GMS service session.
groupInfo	Pointer to the structure holding noOfGroups param and a pointer.

The user should specify the pointer to the structure of type clGmsGroupInfoT, in which GMS will allocate the memory for groupInfo pointer and fills the noOfGroups value. The user should deallocate the memory given with groupInfo pointer.

Return values

CL_ERR_INVALID_HANDLE	On passing an invalid handle.
CL_ERR_INVALID_PARAMETER	On passing an invalid parameter.
CL_ERR_NULL_POINTER	On passing a NULL pointer.

Description:: This API is used to retrieve the information on all the groups existing on the node. The user should pass the pointer to the ClGmsGroupInfoListT data structer. GMS will allocate the memory for all the groups info and fills in the noOfGroups param

Library File:: libClGms

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
	)

Send a Totally ordered multicast messages to all members of a given group.

Parameters

svcHandle	svcHandle provided during clTmsInitialize
groupId	Group Id of the destination group
memberId	memberId of the sender
timeout	timeout value of the API call
dataSize	size of the data being sent in data pointer
data	void pointer pointing to the data to be sent.

Return values

CL_ERR_TRY_AGAIN	Server is not ready to serve group functionality
CL_ERR_VERSION_MISMATCH	Client version not supported
CL_ERR_INVALID_HANDLE	svcHandle is invalid
CL_ERR_NOT_EXIST	Destination group does not exist
CL_ERR_NULL_POINTER	data pointer is NULL
CL_ERR_NO_MEMORY	Could not allocate memory while sending the message
CL_ERR_NO_RESOURCE	Could not allocate resource to send the message
CL_ERR_TIMEOUT	timeout occurred while sending the message
CL_ERR_UNSPECIFIED	Group creation failed with unknown error.

Description:: Create a group. User needs to pass groupName and groupId pointer. GMS will generate a groupId which will be unique across the cluster, and it will be returned through groupId pointer.

Files

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation