Main Page | Modules | Namespace List | Class Hierarchy | Data Structures | Directories | File List | Namespace Members | Data Fields | Globals

ALP Abstract IPC


Typedefs

typedef _AlpChannel AlpChannel
 Opaque type for representing a particular IPC channel (i.e. server).
typedef _AlpConnection AlpConnection
 Opaque type representing a connection between the server and a single client.
typedef _AlpMessage AlpMessage
 Opaque type used to contain the data for a message.
typedef void(* AlpChannelConnectCB )(AlpConnection *connection, gpointer cbData)
 Signature for connect callback function.
typedef void(* AlpChannelDisconnectCB )(AlpConnection *connection, gpointer cbData)
 Signature for disconnect callback function.
typedef void(* AlpMessageReceiveCB )(AlpConnection *connection, AlpMessage *message, gpointer cbData)
 Signature for message receive callback function.

Enumerations

enum  AlpIpcChannelAccessMode { ALP_IPC_CHANNEL_ACCESS_OWNER, ALP_IPC_CHANNEL_ACCESS_ALL }
 Settings for channel access mode. More...
enum  AlpConnectionUsageHint { ALP_IPC_CONNECTION_USAGE_HINT_NONE = 0x0, ALP_IPC_CONNECTION_USAGE_HINT_SYNCH_ONLY = 0x1 }
 Connection usage hints. More...

Functions

AlpChannelalp_ipc_channel_create (const gchar *channelName, AlpIpcChannelAccessMode accessMode)
 Creates an AlpChannel.
alp_status_t alp_ipc_channel_destroy (AlpChannel *channel)
 Destroys an AlpChannel.
alp_status_t alp_ipc_channel_register_connect_callback (AlpChannel *channel, AlpChannelConnectCB callback, gpointer cbData)
 Registers a callback for the server process whenever a client connects.
alp_status_t alp_ipc_channel_register_disconnect_callback (AlpChannel *channel, AlpChannelDisconnectCB callback, gpointer cbData)
 Registers a callback for the server process whenever a client disconnects or exits without disconnecting.
AlpConnectionalp_ipc_channel_connect (const gchar *channelName, AlpConnectionUsageHint hint, AlpChannelConnectCB callback, gpointer cbData)
 Requests a connection to a AlpChannel.
alp_status_t alp_ipc_channel_connect_synch (const gchar *channelName, AlpConnectionUsageHint usageHint, guint timeout, AlpConnection **connection)
 Requests a connection to a AlpChannel.
alp_status_t alp_ipc_channel_disconnect (AlpConnection *connection)
 Disconnects process from an AlpChannel.
void alp_ipc_channel_set_custom_data (AlpChannel *channel, gpointer customData)
 Assigns a pointer to a custom block of data to be stored with this AlpChannel.
gpointer alp_ipc_channel_get_custom_data (AlpChannel *channel)
 Retrieves the pointer to a custom block of data stored with this AlpChannel.
alp_status_t alp_ipc_connection_register_disconnect_callback (AlpConnection *connection, AlpChannelDisconnectCB callback, gpointer cbData)
 Registers to receive a callback when the server disconnects by destroying the channel or exiting.
gint alp_ipc_connection_get_peer_pid (const AlpConnection *connection)
 Returns the process ID of the peer process for this connection.
gint alp_ipc_connection_get_peer_uid (const AlpConnection *connection)
 Returns the user ID of the peer process for this connection.
gint alp_ipc_connection_get_peer_gid (const AlpConnection *connection)
 Returns the group ID of the peer process for this connection.
AlpMessagealp_ipc_message_create ()
 Allocates a AlpMessage structure.
alp_status_t alp_ipc_message_destroy (AlpMessage *message)
 Cleans up and frees all memory associated with the message.
gint alp_ipc_message_get_message_ID (AlpMessage *message)
 Returns the message ID of the message.
alp_status_t alp_ipc_connection_send (AlpConnection *connection, AlpMessage *message)
 Sends a message to the other end of a connection.
alp_status_t alp_ipc_connection_send_with_response (AlpConnection *connection, AlpMessage *message, guint timeout, AlpMessage **response)
 Sends a message to the other end of a connection, then waits for a response message.
alp_status_t alp_ipc_connection_receive (AlpConnection *connection, gint messageID, guint timeout, AlpMessage **message)
 Synchronously receive a message from the other end of a connection.
alp_status_t alp_ipc_connection_register_receive_callback (AlpConnection *connection, AlpMessageReceiveCB callback, gpointer cbData)
 Registers to receive an asynchronous callback when a message is received by the connection.
void alp_ipc_connection_set_custom_data (AlpConnection *connection, gpointer customData)
 Assigns a pointer to a custom block of data to be stored with this AlpConnection.
gpointer alp_ipc_connection_get_custom_data (AlpConnection *connection)
 Retrieves the pointer to a custom block of data stored with this AlpConnection.
alp_status_t alp_ipc_message_pack_start (AlpMessage *message, gint messageID)
 Call to begin to pack a message into an existing AlpMessage struct.
alp_status_t alp_ipc_message_response_pack_start (AlpMessage *message, gint messageID, AlpMessage *messageToRespondTo)
 Call to begin to pack a response message into an existing AlpMessage struct.
alp_status_t alp_ipc_message_pack_end (AlpMessage *message)
 Call to finish packing a message into an existing AlpMessage struct.
alp_status_t alp_ipc_message_pack_int32 (AlpMessage *message, gint32 val)
 Adds an int32 value to the message.
alp_status_t alp_ipc_message_pack_uint32 (AlpMessage *message, guint32 val)
 Adds an uint32 value to the message.
alp_status_t alp_ipc_message_pack_float (AlpMessage *message, gfloat val)
 Adds a float value to the message.
alp_status_t alp_ipc_message_pack_string (AlpMessage *message, const gchar *val)
 Adds a null-terminated string value to the message.
alp_status_t alp_ipc_message_pack_byte_array (AlpMessage *message, guchar *byteArray, guint numElements)
 Adds a array of bytes (i.e. unsigned chars) to the message.
alp_status_t alp_ipc_message_unpack_start (AlpMessage *message)
 Call to begin unpacking a message from an AlpMessage struct.
alp_status_t alp_ipc_message_unpack_end (AlpMessage *message)
 Call to finish unpacking a message from an AlpMessage struct.
alp_status_t alp_ipc_message_unpack_int32 (AlpMessage *message, gint32 *val)
 Unpacks an int32 value from the message.
alp_status_t alp_ipc_message_unpack_uint32 (AlpMessage *message, guint32 *val)
 Unpacks an uint32 value from the message.
alp_status_t alp_ipc_message_unpack_float (AlpMessage *message, gfloat *val)
 Unpacks a float value from the message.
alp_status_t alp_ipc_message_unpack_string (AlpMessage *message, gchar **val)
 Unpacks a null-terminated string from the message.
alp_status_t alp_ipc_message_unpack_byte_array (AlpMessage *message, guchar **array, guint *numElements)
 Unpacks an array of bytes (i.e. unsigned chars) from the message.


Typedef Documentation

typedef struct _AlpChannel AlpChannel
 

Opaque type for representing a particular IPC channel (i.e. server).

typedef void(* AlpChannelConnectCB)(AlpConnection *connection, gpointer cbData)
 

Signature for connect callback function.

typedef void(* AlpChannelDisconnectCB)(AlpConnection *connection, gpointer cbData)
 

Signature for disconnect callback function.

typedef struct _AlpConnection AlpConnection
 

Opaque type representing a connection between the server and a single client.

typedef struct _AlpMessage AlpMessage
 

Opaque type used to contain the data for a message.

typedef void(* AlpMessageReceiveCB)(AlpConnection *connection, AlpMessage *message, gpointer cbData)
 

Signature for message receive callback function.


Enumeration Type Documentation

enum AlpConnectionUsageHint
 

Connection usage hints.

Enumerator:
ALP_IPC_CONNECTION_USAGE_HINT_NONE 
ALP_IPC_CONNECTION_USAGE_HINT_SYNCH_ONLY 

enum AlpIpcChannelAccessMode
 

Settings for channel access mode.

Enumerator:
ALP_IPC_CHANNEL_ACCESS_OWNER 
ALP_IPC_CHANNEL_ACCESS_ALL 


Function Documentation

AlpConnection* alp_ipc_channel_connect const gchar *  channelName,
AlpConnectionUsageHint  hint,
AlpChannelConnectCB  callback,
gpointer  cbData
 

Requests a connection to a AlpChannel.

Can be called by one or more processes to connect as clients of the channel

Does not block, rather a callback is invoked when the connection is ready

Parameters:
channelName Name of the channel to connect to
usageHint Provides hint of how connection will be used. The IPC implementation may use this hint to optimize how the connection is set-up. The param is a bitwise OR of the AlpConnectionUsageHint enum values. Currently, the only values are ALP_IPC_CONNECTION_USAGE_HINT_NONE (no flags set) and ALP_IPC_CONNECTION_USAGE_HINT_SYNCH_ONLY which indicates that the connection will only be used for synchronous message sending (i.e. no received callback is registered, all messages are received using only alp_ipc_connection_receive and alp_ipc_connection_send_with_response). Use ALP_IPC_CONNECTION_USAGE_HINT_NONE unless you REALLY understand what you're doing!
callback Callback function to be invoked when the connection is ready
cbData Pointer to data for the callback function
Returns:
A pointer to the connection if successful

NULL if the connection cannot be created

alp_status_t alp_ipc_channel_connect_synch const gchar *  channelName,
AlpConnectionUsageHint  usageHint,
guint  timeout,
AlpConnection **  connection
 

Requests a connection to a AlpChannel.

Can be called by one or more processes to connect as clients of the channel

The call blocks until the connection is ready or until the number of milliseconds specified by the timeout parameter have elapsed.

The caller passes in an AlpConnection** to receive the pointer to the new connection. A valid AlpConnection* is returned only if the function's return status is ALP_STATUS_OK. Otherwise, the returned connection parameter is set to NULL.

The caller is responsible for destroying the returned connection with alp_ipc_connection_destory.

NOTE: If the server has crashed unexpectedly, there may be cases where ALP_STATUS_IPC_ERROR is returned instead of ALP_STATUS_IPC_NO_SERVER.

Parameters:
channelName Name of the channel to connect to
usageHint Provides hint of how connection will be used. The IPC implementation may use this hint to optimize how the connection is set-up. The param is a bitwise OR of the AlpConnectionUsageHint enum values. Currently, the only values are ALP_IPC_CONNECTION_USAGE_HINT_NONE (no flags set) and ALP_IPC_CONNECTION_USAGE_HINT_SYNCH_ONLY which indicates that the connection will only be used for synchronous message sending (i.e. no received callback is registered, all messages are received using only alp_ipc_connection_receive and alp_ipc_connection_send_with_response). Use ALP_IPC_CONNECTION_USAGE_HINT_NONE unless you REALLY understand what you're doing!
timeout Maximum amount of time to block before returning in milliseconds. Specifying a timeout value of 0 causes the function to never unblock until a message is received. If the timeout is reached before a message is received, the function returns NULL.
connection Pointer to receive the AlpConnection*.
Returns:
ALP_STATUS_OK if the connection was created

ALP_STATUS_IPC_TIMEOUT if the timeout occurred

ALP_STATUS_IPC_NO_SERVER if the server is not running

ALP_STATUS_IPC_ERROR if any other condition occurred

NULL if the connection cannot be created or if the timeout occurred

AlpChannel* alp_ipc_channel_create const gchar *  channelName,
AlpIpcChannelAccessMode  accessMode
 

Creates an AlpChannel.

Should only be called by the server for a given channel name

The process that makes the call (i.e. the server for the channel) is responsible for calling alp_ipc_channel_destroy to clean-up the channel and its connections when finished.

Parameters:
channelName A string containing the name of the channel to be created
accessMode Sets permissions for who may access the channel. Possible values are ALP_IPC_CHANNEL_ACCESS_OWNER and ALP_IPC_CHANNEL_ACCESS_ALL. For ALP_IPC_CHANNEL_ACCESS_OWNER, only processes with the same owner as the channel creator will be able to connect to the IPC channel. For ALP_IPC_CHANNEL_ACCESS_ALL, any process can connect to the IPC channel.
Returns:
A pointer to the AlpChannel for the server if it was created OK

NULL otherwise

alp_status_t alp_ipc_channel_destroy AlpChannel channel  ) 
 

Destroys an AlpChannel.

Should only be called by the process that creating the channel by calling alp_ipc_channel_create()

Notifies clients that have registered a disconnect callback, then destroys all memory and closes any file descriptors used internally by the channel

Parameters:
channel Pointer to the AlpChannel to be destroyed
Returns:
ALP_STATUS_OK if no error

ALP_STATUS_IPC_ERROR if any error condition occurred

alp_status_t alp_ipc_channel_disconnect AlpConnection connection  ) 
 

Disconnects process from an AlpChannel.

This should only be called by the client processes that connected to the channel using alp_ipc_channel_connect().

This will trigger any registered disconnect callback in the server process when any client disconnects.

This also destroys all memory and closes any file descriptors used internally by the connection.

Parameters:
connection Pointer to the AlpConnection to disconnect
Returns:
ALP_STATUS_OK if no error

ALP_STATUS_IPC_ERROR if any error condition occurred

gpointer alp_ipc_channel_get_custom_data AlpChannel channel  ) 
 

Retrieves the pointer to a custom block of data stored with this AlpChannel.

The user owns the block of memory referenced by the custom data pointer and must free it when it is no longer needed.

Parameters:
channel Pointer to the AlpChannel where the custom data pointer is stored
Returns:
Pointer to the custom data stored with this AlpChannel

NULL if no custom data has been set

alp_status_t alp_ipc_channel_register_connect_callback AlpChannel channel,
AlpChannelConnectCB  callback,
gpointer  cbData
 

Registers a callback for the server process whenever a client connects.

Only one connect callback function can be registered at any time. If a second call to register a callback is made, it replaces the first call. Passing NULL as the callback function deletes the callback.

NOTE: If the server process wishes to send messages to the client who's connecting, it must store the AlpConnection* passed to it in the callback when the client connects.

Parameters:
channel Pointer to the AlpChannel the callback is being added to
callback Callback function to be invoked when a client connects
cbData Pointer to data for the callback function
Returns:
ALP_STATUS_OK if no error

ALP_STATUS_IPC_ERROR if any error condition occurred

alp_status_t alp_ipc_channel_register_disconnect_callback AlpChannel channel,
AlpChannelDisconnectCB  callback,
gpointer  cbData
 

Registers a callback for the server process whenever a client disconnects or exits without disconnecting.

Only one disconnect callback function can be registered at any time. If a second call to register a callback is made, it replaces the first call. Passing NULL as the callback function deletes the callback.

Parameters:
channel Pointer to the AlpChannel the callback is being added to
callback Callback function to be invoked when a client disconnects
cbData Pointer to data for the callback function
Returns:
ALP_STATUS_OK if no error

ALP_STATUS_IPC_ERROR if any error condition occurred

void alp_ipc_channel_set_custom_data AlpChannel channel,
gpointer  customData
 

Assigns a pointer to a custom block of data to be stored with this AlpChannel.

The user owns the block of memory referenced by the custom data pointer and must free it when it is no longer needed.

Parameters:
channel Pointer to the AlpChannel where the custom data pointer is to be stored
customData Pointer to the custom data to be stored with the AlpChannel

gpointer alp_ipc_connection_get_custom_data AlpConnection connection  ) 
 

Retrieves the pointer to a custom block of data stored with this AlpConnection.

The user owns the block of memory referenced by the custom data pointer and must free it when it is no longer needed.

Parameters:
connection Pointer to the AlpConnection where the custom data pointer is stored
Returns:
Pointer to the custom data stored with this AlpConnection

NULL if no custom data has been set

gint alp_ipc_connection_get_peer_gid const AlpConnection connection  ) 
 

Returns the group ID of the peer process for this connection.

Parameters:
connection AlpConnection pointer
Returns:
The group ID of the peer process for the connection

-1 if connection is NULL or if the connection is not connected

gint alp_ipc_connection_get_peer_pid const AlpConnection connection  ) 
 

Returns the process ID of the peer process for this connection.

Parameters:
connection AlpConnection pointer
Returns:
The process ID of the peer process for the connection

-1 if connection is NULL or if the connection is not connected

gint alp_ipc_connection_get_peer_uid const AlpConnection connection  ) 
 

Returns the user ID of the peer process for this connection.

Parameters:
connection AlpConnection pointer
Returns:
The user ID of the peer process for the connection

-1 if connection is NULL or if the connection is not connected

alp_status_t alp_ipc_connection_receive AlpConnection connection,
gint  messageID,
guint  timeout,
AlpMessage **  message
 

Synchronously receive a message from the other end of a connection.

The caller passes in an AlpMessage** to receive the pointer to the received message. The caller is responsible for deleting the AlpMessage* when finished. A valid AlpMessage* is returned only if the function's return status is ALP_STATUS_OK. Otherwise, the returned message parameter is set to NULL.

The caller can specify to wait for a message that matches a particular message ID or can wait for any message to be received on the connection by setting the messageID parameter to ALP_IPC_RECEIVE_ANY.

If you specify a messageID of ALP_IPC_RECEIVE_ANY, alp_ipc_connection_receive will unblock and return the first message received on the connection. If you specify any other value for messageID, alp_ipc_connection_receive will block until a message with the specified messageID has been received. In either case, the function will return if the specified timeout interval is reached before a message is received. Any messages received while blocked that do not correspond to the requested message ID are automatically queued and delivered once alp_ipc_connection_receive returns.

The caller is responsible for deleting the AlpMessage struct returned by callingalp_ipc_message_destroy.

Parameters:
connection Pointer to the AlpConnection on which the message is to be received
messageID Specifies which message ID to wait for.
timeout Maximum amount of time to block before returning in milliseconds. Specifying a timeout value of 0 causes the function to never unblock until a message is received. If the timeout is reached before a message is received, the status code ALP_IPC_TIMEOUT is returned.
message Pointer to receive the AlpMessage*.
Returns:
ALP_STATUS_OK if no error

ALP_STATUS_IPC_TIMEOUT if the timeout occurs before the message is received

ALP_STATUS_IPC_BROKEN_CONNECTION if the connection is broken before the timeout or a message is received

ALP_STATUS_IPC_NOT_CONNECTED if the connection is not ready for use (usually because the other end of the connection has not created)

ALP_STATUS_IPC_INVALID_RESPONSE if the connection receives a message that's intended to be a response to an alp_ipc_connection_send_with_response() call

ALP_STATUS_IPC_ERROR for other error conditions

alp_status_t alp_ipc_connection_register_disconnect_callback AlpConnection connection,
AlpChannelDisconnectCB  callback,
gpointer  cbData
 

Registers to receive a callback when the server disconnects by destroying the channel or exiting.

Only one disconnect callback function can be registered at any time. If a second call to register a callback is made, it replaces the first call. Passing NULL as the callback function deletes the callback.

Parameters:
connection Pointer to the AlpConnection the callback is being added to
callback Callback function to be invoked when the server disconnects
cbData Pointer to data for the callback function
Returns:
ALP_STATUS_OK if no error

ALP_STATUS_IPC_ERROR if any error condition occurred

alp_status_t alp_ipc_connection_register_receive_callback AlpConnection connection,
AlpMessageReceiveCB  callback,
gpointer  cbData
 

Registers to receive an asynchronous callback when a message is received by the connection.

Only one receive callback function can be registered at any time. If a second call to register a callback is made, it replaces the first call. Passing NULL as the callback function deletes the callback.

The cbData structure specified is passed to the callback along with a pointer to the AlpMessage. The message ID and the format of the message are available when the callback is made, but the other data in the message must be unpacked using the various alp_ipc_message_unpack_* functions.

The caller is responsible for deleting the AlpMessage structure returned by calling alp_ipc_message_destroy();

Requires that a GMainLoop is running in the process

Parameters:
connection Pointer to the AlpConnection the callback is being added to
callback Callback function to be invoked when a message is received
cbData Pointer to data for the callback function
Returns:
ALP_STATUS_OK if no error

ALP_STATUS_IPC_ERROR if any error condition occurred

alp_status_t alp_ipc_connection_send AlpConnection connection,
AlpMessage message
 

Sends a message to the other end of a connection.

The send is asynchronous (i.e. non-blocking)

Parameters:
connection Pointer to the AlpConnection on which the message is to be sent
message Pointer to the AlpMessage to send
Returns:
ALP_STATUS_OK if no error

ALP_STATUS_IPC_NOT_CONNECTED if the connection is not ready for use (usually because the other end of the connection has not created)

ALP_STATUS_IPC_ERROR for other error conditions

alp_status_t alp_ipc_connection_send_with_response AlpConnection connection,
AlpMessage message,
guint  timeout,
AlpMessage **  response
 

Sends a message to the other end of a connection, then waits for a response message.

The caller passes in an AlpMessage** to receive the pointer to the response message. The caller is responsible for deleting both the original and the response AlpMessage*'s when finished. The receiver is also responsible for deleting the AlpMessage* it receives and the AlpMessage* response is returns. A valid AlpMessage* is returned only if the function's return status is ALP_STATUS_OK. Otherwise, the returned message parameter is set to NULL.

alp_ipc_connection_send_with_response blocks until a response message for the sent message has been received. The function will return if the specified timeout interval is reached before a message is received. Any messages received while blocked that do not correspond to the requested message ID are automatically queued and delivered once alp_ipc_connection_send_with_response returns.

The receiver of the message should should a response to the message, using alp_message_response_pack_start() instead of alp_message_pack_start() when creating the message.

The caller is responsible for deleting the response AlpMessage struct returned by calling alp_ipc_message_destroy.

Parameters:
connection Pointer to the AlpConnection on which the message is to be sent
message Pointer to the AlpMessage to send
timeout Maximum amount of time to block before returning in milliseconds. Specifying a timeout value of 0 causes the function to never unblock until a message is received. If the timeout is reached before a message is received, the status code ALP_IPC_TIMEOUT is returned.
response Pointer to receive the response AlpMessage*.
Returns:
ALP_STATUS_OK if no error

ALP_STATUS_IPC_TIMEOUT if the timeout occurs before the message is received

ALP_STATUS_IPC_BROKEN_CONNECTION if the connection is broken before the timeout or a message is received

ALP_STATUS_IPC_NOT_CONNECTED if the connection is not ready for use (usually because the other end of the connection has not created)

ALP_STATUS_IPC_INVALID_RESPONSE if the connection receives a message that's intended to be a response to a different message

ALP_STATUS_IPC_ERROR for other error conditions

void alp_ipc_connection_set_custom_data AlpConnection connection,
gpointer  customData
 

Assigns a pointer to a custom block of data to be stored with this AlpConnection.

The user owns the block of memory referenced by the custom data pointer and must free it when it is no longer needed.

Parameters:
connection Pointer to the AlpConnection where the custom data pointer is to be stored
customData Pointer to the custom data to be stored with the AlpConnection

AlpMessage* alp_ipc_message_create  ) 
 

Allocates a AlpMessage structure.

Returns:
A pointer to the allocated AlpMessage structure if successfull

NULL if the allocation fails

alp_status_t alp_ipc_message_destroy AlpMessage message  ) 
 

Cleans up and frees all memory associated with the message.

Parameters:
message Pointer to the message to be destroyed
Returns:
ALP_STATUS_OK if no error

ALP_STATUS_IPC_ERROR if any error condition occurred

gint alp_ipc_message_get_message_ID AlpMessage message  ) 
 

Returns the message ID of the message.

The message ID is a integer value that can be any non-negative value agreed upon by the clients and server of a particular channel. Negative values are reserved for internal use by the IPC module. It is set by the sender of the message in the call to alp_ipc_message_start_pack().

Parameters:
message Pointer to an AlpMessage
Returns:
The message ID of the message

alp_status_t alp_ipc_message_pack_byte_array AlpMessage message,
guchar *  byteArray,
guint  numElements
 

Adds a array of bytes (i.e. unsigned chars) to the message.

Parameters:
message Pointer to the AlpMessage being packed
byteArray Pointer to the byte array. If byteArray is NULL, numElements will be set to zero.
numElements Number of elements to pack.
Returns:
ALP_STATUS_OK if no error

ALP_STATUS_IPC_ERROR if any error condition occurred

alp_status_t alp_ipc_message_pack_end AlpMessage message  ) 
 

Call to finish packing a message into an existing AlpMessage struct.

Parameters:
message Pointer to the AlpMessage being packed
Returns:
ALP_STATUS_OK if no error

ALP_STATUS_IPC_ERROR if any error condition occurred

alp_status_t alp_ipc_message_pack_float AlpMessage message,
gfloat  val
 

Adds a float value to the message.

Parameters:
message Pointer to the AlpMessage being packed
val The floating point value to be appended to the message
Returns:
ALP_STATUS_OK if no error

ALP_STATUS_IPC_ERROR if any error condition occurred

alp_status_t alp_ipc_message_pack_int32 AlpMessage message,
gint32  val
 

Adds an int32 value to the message.

Parameters:
message Pointer to the AlpMessage being packed
val The integer value to be appended to the message
Returns:
ALP_STATUS_OK if no error

ALP_STATUS_IPC_ERROR if any error condition occurred

alp_status_t alp_ipc_message_pack_start AlpMessage message,
gint  messageID
 

Call to begin to pack a message into an existing AlpMessage struct.

Sets the message ID and prepares internal buffers for packing the message data. If reusing an AlpMessage struct, calling alp_ipc_message_pack_start() causes any old message info to be discarded.

Packing a message involves calling alp_ipc_message_pack_start, followed by zero or more calls to alp_ipc_message_pack_<type> where type is the value type being added to the message (e.g. int32, string, etc.), followed by alp_ipc_message_pack_end.

Parameters:
message Pointer to the AlpMessage being packed
messageID An integer value that can be any non-negative value agreed upon by the clients and server of a particular channel. Negative values are reserved for internal use by the IPC library.
Returns:
ALP_STATUS_OK if no error

ALP_STATUS_IPC_ERROR if any error condition occurred

alp_status_t alp_ipc_message_pack_string AlpMessage message,
const gchar *  val
 

Adds a null-terminated string value to the message.

Parameters:
message Pointer to the AlpMessage being packed
val The string to be appended to the message. If val is NULL, the receiver will get a NULL pointer when unpacking the message.
Returns:
ALP_STATUS_OK if no error

ALP_STATUS_IPC_ERROR if any error condition occurred

alp_status_t alp_ipc_message_pack_uint32 AlpMessage message,
guint32  val
 

Adds an uint32 value to the message.

Parameters:
message Pointer to the AlpMessage being packed
val The unsigned integer value to be appended to the message
Returns:
ALP_STATUS_OK if no error

ALP_STATUS_IPC_ERROR if any error condition occurred

alp_status_t alp_ipc_message_response_pack_start AlpMessage message,
gint  messageID,
AlpMessage messageToRespondTo
 

Call to begin to pack a response message into an existing AlpMessage struct.

Sets the message ID and response identifier and prepares internal buffers for packing the message data. If reusing an AlpMessage struct, calling alp_ipc_response_pack_start() causes any old message info to be discarded.

Packing a response message involves calling alp_ipc_response_pack_start, followed by zero or more calls to alp_ipc_message_pack_<type> where type is the value type being added to the message (e.g. int32, string, etc.), followed by alp_ipc_message_pack_end.

Parameters:
message Pointer to the AlpMessage being packed
messageID An integer value that can be any non-negative value agreed upon by the clients and server of a particular channel. Negative values are reserved for internal use by the IPC library.
messageToRespondTo Pointer to the AlpMessage being responded to
Returns:
ALP_STATUS_OK if no error

ALP_STATUS_IPC_ERROR if any error condition occurred

alp_status_t alp_ipc_message_unpack_byte_array AlpMessage message,
guchar **  array,
guint *  numElements
 

Unpacks an array of bytes (i.e. unsigned chars) from the message.

Storage for the byte array is allocated and must be freed by the caller with g_free()

Parameters:
message Pointer to the AlpMessage to unpack
array Pointer to the guchar* that is allocated to store the array in. If numElements is zero, the pointer (i.e. *array) will be set to NULL.
numElements Pointer to an integer containing the number of elements in the array.
Returns:
ALP_STATUS_OK if no error

ALP_STATUS_IPC_ERROR if any error condition occurred

alp_status_t alp_ipc_message_unpack_end AlpMessage message  ) 
 

Call to finish unpacking a message from an AlpMessage struct.

Parameters:
message Pointer to the AlpMessage to unpack
Returns:
ALP_STATUS_OK if no error

ALP_STATUS_IPC_ERROR if any error condition occurred

alp_status_t alp_ipc_message_unpack_float AlpMessage message,
gfloat *  val
 

Unpacks a float value from the message.

Parameters:
message Pointer to the AlpMessage to unpack
val Pointer to a float to store the unpacked value in
Returns:
ALP_STATUS_OK if no error

ALP_STATUS_IPC_ERROR if any error condition occurred

alp_status_t alp_ipc_message_unpack_int32 AlpMessage message,
gint32 *  val
 

Unpacks an int32 value from the message.

Parameters:
message Pointer to the AlpMessage to unpack
val Pointer to an integer to store the unpacked value in
Returns:
ALP_STATUS_OK if no error

ALP_STATUS_IPC_ERROR if any error condition occurred

alp_status_t alp_ipc_message_unpack_start AlpMessage message  ) 
 

Call to begin unpacking a message from an AlpMessage struct.

Unpacking a message involves calling alp_ipc_message_unpack_start, followed by zero or more calls to alp_ipc_message_unpack_<type> where type is the value type being added to the message (e.g. int32, string, etc.), followed by alp_ipc_message_unpack_end.

Messages can be unpacked more than once by calling alp_ipc_message_unpack_start() a second time to reset the internal state

Parameters:
message Pointer to the AlpMessage to unpack
Returns:
ALP_STATUS_OK if no error

ALP_STATUS_IPC_ERROR if any error condition occurred

alp_status_t alp_ipc_message_unpack_string AlpMessage message,
gchar **  val
 

Unpacks a null-terminated string from the message.

Storage for the unpacked string is allocated and must be freed by the caller with g_free()

Parameters:
message Pointer to the AlpMessage to unpack
val Pointer to an gchar* to store the unpacked value in. If the sender packed a NULL string pointer, *val will be set to NULL.
Returns:
ALP_STATUS_OK if no error

ALP_STATUS_IPC_ERROR if any error condition occurred

alp_status_t alp_ipc_message_unpack_uint32 AlpMessage message,
guint32 *  val
 

Unpacks an uint32 value from the message.

Parameters:
message Pointer to the AlpMessage to unpack
val Pointer to an unsigned integer to store the unpacked value in
Returns:
ALP_STATUS_OK if no error

ALP_STATUS_IPC_ERROR if any error condition occurred


Generated on Sat Dec 16 20:29:50 2006 for hiker-0.9 by  doxygen 1.4.4