6.4.1 Registering Interaction Sides

Before exchanging data packets, an application program registers sides taking part in the interaction. A side handle refers to a registered interaction side.

Data type: qsmm_side_t

This is a type for a side handle. It is a pointer, so variables of this type can be NULL. The function qsmm_side_create allocates a new side handle. The function qsmm_side_destroy frees an existing side handle. You can pass an allocated side handle to API functions taking an argument of qsmm_side_t type until freeing the handle.

Use the following functions to register and unregister an interaction side.

Function: int qsmm_side_create (const char *name_p, qsmm_side_t *side_p)

This function registers an interaction side named name_p and stores a newly allocated side handle in *side_p if side_p is not NULL. If side_p is NULL, the function has no effect. The name name_p identifies the interaction side in the trace log of data packets exchange between sides. If name_p is not NULL, the function creates a copy of name_p and stores the copy in an internal structure.

The function returns a non-negative value on success or a negative error code on failure in registering a side. Currently, the function can return the following error codes.

QSMM_ERR_PTHREAD

A POSIX threads API error.

QSMM_ERR_NOMEM

There was not enough memory to register a side.

Function: void qsmm_side_destroy (qsmm_side_t side)

This function unregisters an interaction side specified by a handle side. You must not use the side handle after unregistering the side. If side is NULL, the function has no effect.

Use the following function to get the name of an interaction side specified by its handle.

Function: const char * qsmm_get_side_name (qsmm_side_t side)

This function returns the name of an interaction side specified when creating it. If the interaction side does not have a name specified, the function returns NULL.