Message Struct Reference

Collaboration diagram for Message:

Collaboration graph

Public Methods

struct KeyParam* Message_get_key_param (struct Message *ptr_message)

struct Message* Message_new (size_t sizeof_message)

cyid_t Message_get_sender_id (struct Message *ptr_message)

bool Message_is_broadcast (struct Message *ptr_message)

bool Message_post (struct Message *ptr_message, char *sz_process_name, cyid_t cyid)

void Message_post_all (struct Message *ptr_message, short mask)

void* Message_deliver (struct Message *ptr_message, char *sz_process_name, cyid_t cyid, clock_t timeout)

delivery_t Message_check_delivery (struct Message *ptr_message)

delivery_t Message_wait_delivery (struct Message *ptr_message, struct Flag *ptr_flag)

bool Message_has_buffer (struct Message *ptr_message)

struct Buffer* Message_get_buffer (struct Message *ptr_message)

void Message_attach_buffer (struct Message *ptr_message, struct Buffer *ptr_buffer)

void Message_copy (struct Message *ptr_message, struct Message *ptr_templ)

void Message_delete (struct Message *ptr_message)

Public Attributes

struct Message* next

char* dst_name

cyid_t cyid_from

cyid_t cyid_to

bool deleted

short msgid

long param [2]

Detailed Description

Structure for interprocess communications; can be sent either locally or remotely.

See also:: Messaging

Member Function Documentation

void Message_attach_buffer ( struct Message * ptr_message,

struct Buffer * ptr_buffer )

Attaches a buffer to the message.
Note: the Buffer recycles automatically along with the Message.

Parameters:: ptr_message A pointer to the initialized Message object

ptr_buffer A pointer to the initialized Buffer object to attach

Returns:

None

 #include <cybiko.h>
 #define MSG_CHAT_STRING MSG_USER + 1
 ...
 struct module_t main_module;
 struct Buffer message_buffer;
 char partner_name[9];
 cyid_t partner_id;
 ...
 init_module( &main_module );
 ...
 partner_id = select_game_partner( main_module.m_process,
 "Billiard",
 SGP_CYBIKO | SGP_HOT_SEAT,
 partner_name );
 if( partner_id )
 {
 ...
 struct Message* ptr_message = Message_new( sizeof( struct Message ) );
 ptr_message->msgid = MSG_CHAT_STRING;
 Buffer_ctor( &message_buffer, 20, 10 );
 Buffer_store_string( &message_buffer, "Hey, dude!", 0 );
 Message_attach_buffer( ptr_message, &message_buffer );
 Message_deliver( ptr_message, "Billiard", partner_id, 60*1000 );
 }
 ...

delivery_t Message_check_delivery ( struct Message * ptr_message )

Checks the delivery state.

Parameters:: ptr_message A pointer to the initialized Message object

Returns:

Delivery state

 #include <cybiko.h>
 #define MSG_TEST MSG_USER + 1
 ...
 struct module_t main_module;
 char partner_name[9];
 cyid_t partner_id;
 struct Message* ptr_message;
 delivery_t delivery_result;
 ...
 init_module( &main_module );
 ...
 partner_id = select_game_partner( main_module.m_process,
 "Billiard",
 SGP_CYBIKO | SGP_HOT_SEAT,
 partner_name );
 if( partner_id )
 {
 ...
 ptr_message = Message_new( sizeof( struct Message ) );
 ptr_message->msgid = MSG_TEST;
 // Sends message to "Billiard" application on the remote computer.
 Message_deliver( ptr_message, "Billiard", partner_id, 60*1000 );
 }
 while(1)
 {
 cWinApp_pause( main_module.m_process, 250 );
 delivery_result = Message_check_delivery( ptr_message );
 if( delivery_result == DL_SUCCESS )
 {
 TRACE( "Message was delivered successfully" );
 break;
 }
 else if( ( delivery_result == DL_ABORT ) 
 || ( delivery_result == DL_TIMEOUT ) )
 {
 TRACE( "Message was not delivered successfully" );
 break;
 }
 }
 ...

See also:: DL_INQUEUE, DL_WAIT, DL_ABORT, DL_TIMEOUT, DL_SUCCESS.

void Message_copy ( struct Message * ptr_message,

struct Message * ptr_templ )

Makes the destination Message an exact copy of the source Message.

Parameters:: ptr_message A pointer to the destination Message object

ptr_templ A pointer to the source Message object

Returns:

None

 #include <cybiko.h>
 #define MSG_TEST MSG_USER + 1
 ...
 struct Message* ptr_message = Message_new( sizeof( struct Message ) );
 struct Message* ptr_message_repeat = Message_new( sizeof( struct Message ) );
 ptr_message->msgid = MSG_TEST;
 ...
 Message_copy( ptr_message_repeat, ptr_message );
 // Sends the message to the 'data_reciever' process which 
 // is on the same device.
 Message_post( ptr_message, "data_reciever", get_own_id() );
 // Repeats message.
 Message_post( ptr_message_repeat, "data_reciever", get_own_id() );
 ...

void Message_delete ( struct Message * ptr_message )

Deletes a message.

Parameters:: ptr_message A pointer to the initialized Message object

Returns:

None

 #include <cybiko.h>
 #define MSG_TEST MSG_USER + 1
 ...
 struct Message* ptr_message = Message_new( sizeof( struct Message ) );
 ptr_message->msgid = MSG_TEST;
 // Sends the message to the 'data_reciever' process which 
 // is on the same computer.
 Message_post( ptr_message, "data_reciever", get_own_id() );
 ...

void * Message_deliver ( struct Message * ptr_message,

char * sz_process_name,

cyid_t cyid,

clock_t timeout )

Delivers a message to a specified target, with delivery result notification.

Parameters:: ptr_message A pointer to the initialized Message object

sz_process_name The target process' name

cyid The target device's Cy ID

timeout A special time to wait. If the Message is not delivered to the target during the timeout, then the delivery state becomes DL_TIMEOUT

Returns:

None

 #include <cybiko.h>
 #define MSG_TEST MSG_USER + 1
 ...
 struct module_t main_module;
 struct Flag delivery_flag;
 char partner_name[9];
 cyid_t partner_id;
 struct Message* ptr_message;
 ...
 init_module( &main_module );
 ...
 partner_id = select_game_partner( main_module.m_process,
 "Billiard",
 SGP_CYBIKO | SGP_HOT_SEAT,
 partner_name );
 if( partner_id )
 {
 ...
 ptr_message = Message_new( sizeof( struct Message ) );
 ptr_message->msgid = MSG_TEST;
 // Sends message to the "Billiard" application on the remote computer.
 Message_deliver( ptr_message, "Billiard", partner_id, 60*1000 );
 }
 Flag_ctor(&delivery_flag, "MessageMutex", TRUE);
 if( Message_wait_delivery( ptr_message, &delivery_flag ) == DL_SUCCESS )
 {
 TRACE( "Message was delivered successfully" );
 }
 Flag_dtor(&delivery_flag, LEAVE_MEMORY);
 ...

struct Buffer * Message_get_buffer ( struct Message * ptr_message )

Gets a pointer to the attached buffer.
Note, the Buffer created by the system when that receives the message will recycle automatically along with the Message.

Parameters:: ptr_message A pointer to the initialized Message object

Returns:

A pointer to the Buffer object

 #include <cybiko.h>
 #define MSG_CHAT_STRING MSG_USER + 1
 ...
 struct module_t main_module;
 char sz_string_text[32];
 ...
 init_module( &main_module );
 ...
 struct Message* ptr_message = cWinApp_get_message( main_module.m_process, 
 0, 
 1, 
 MSG_CHAT_STRING );
 if( ptr_message->msgid == MSG_CHAT_STRING )
 {
 if( Message_has_buffer( ptr_message ) )
 {
 Buffer_load( Message_get_buffer( ptr_message ), 
 sz_string_text, 
 0, 
 0 );
 TRACE( "Message from the opponent: %s", sz_string_text );
 }
 }
 ...

See also:: Message_has_buffer.

struct KeyParam * Message_get_key_param ( struct Message * ptr_message )

Returns a pointer to the message's KeyParam structure.

Parameters:: ptr_message A pointer to the initialized Message object

Returns:

A pointer to the KeyParam structure of the message

 #include <cybiko.h>
 ...
 struct module_t main_module;
 struct Message* ptr_message;
 ...
 init_module( &main_module );
 ...
 ptr_message = cWinApp_get_message( main_module.m_process, 
 0, 
 1, 
 MSG_USER );
 if( ptr_message->msgid == MSG_KEYDOWN )
 {
 if( Message_get_key_param( ptr_message )->scancode == KEY_ESC )
 {
 // Processes key 'Esc'.
 }
 }
 ...

cyid_t Message_get_sender_id ( struct Message * ptr_message )

Returns the 32-bit device ID (CyID) of the Message's sender.

Parameters:: ptr_message A pointer to the initialized Message object

Returns:

The 32-bit device ID (CyID) of the Message's sender

bool Message_has_buffer ( struct Message * ptr_message )

Tests whether the Message has an attached buffer.

Parameters:: ptr_message A pointer to the initialized Message object

Returns:

TRUE if the message has a buffer

 #include <cybiko.h>
 #define MSG_CHAT_STRING MSG_USER + 1
 ...
 struct module_t main_module;
 char sz_string_text[32];
 ...
 init_module( &main_module );
 ...
 struct Message* ptr_message = cWinApp_get_message( main_module.m_process, 
 0, 
 1, 
 MSG_CHAT_STRING );
 if( ptr_message->msgid == MSG_CHAT_STRING )
 {
 if( Message_has_buffer( ptr_message ) )
 {
 Buffer_load( Message_get_buffer( ptr_message ), 
 sz_string_text , 
 0, 
 0 );
 TRACE( "Message from the opponent: %s", sz_string_text );
 }
 }
 ...

See also:: Message_get_buffer.

bool Message_is_broadcast ( struct Message * ptr_message )

Determines if the message has no specific address.

Parameters:: ptr_message A pointer to the initialized Message object

Returns:

TRUE if the message has no specific address

 #include <cybiko.h>
 #define MSG_TASK_REQUEST MSG_USER + 1
 ...
 struct module_t main_module;
 ...
 init_module( &main_module );
 ...
 struct Message* ptr_message = cWinApp_get_message( main_module.m_process, 
 0, 
 1, 
 MSG_TASK_REQUEST );
 if( Message_is_broadcast( ptr_message ) )
 {
 // Declines task.
 }
 else
 {
 // Accepts task.
 }
 ...

struct Message * Message_new ( size_t sizeof_message )

Returns a new Message from the system stores.

Parameters:: sizeof_message The size of the Message structure

Returns:

A pointer to the Message object

 #include <cybiko.h>
 #define MSG_TEST MSG_USER + 1
 ...
 struct Message* ptr_message = Message_new( sizeof( struct Message ) );
 ptr_message->msgid = MSG_TEST;
 // Sends the message to the 'data_reciever' process which 
 // is on the same computer.
 Message_post( ptr_message, "data_reciever", get_own_id() );
 ...

bool Message_post ( struct Message * ptr_message,

char * sz_process_name,

cyid_t cyid )

Posts a message to a specified target.

Parameters:: ptr_message A pointer to the initialized Message object.

sz_process_name The target process' name

cyid The target computer's Cy ID

Returns:

TRUE if a local Message was put into the Process' Queue

 #include <cybiko.h>
 #define MSG_TEST MSG_USER + 1
 ...
 struct Message* ptr_message = Message_new( sizeof( struct Message ) );
 ptr_message->msgid = MSG_TEST;
 // Sends the message to the 'data_reciever' process which 
 // is on the same computer.
 Message_post( ptr_message, "data_reciever", get_own_id() );
 ...

See also:: Message_post_all.

void Message_post_all ( struct Message * ptr_message,

short mask )

Posts a message to all Queues.

Parameters:: ptr_message A pointer to the initialized Message object.

mask One of the following: QF_NONE, QF_DEVICES, QF_FILES, QF_APPMASK, QF_ALL.

Returns:

None

 #include <cybiko.h>
 #define MSG_TEST MSG_USER + 1
 ...
 struct Message* ptr_message = Message_new( sizeof( struct Message ) );
 ptr_message->msgid = MSG_TEST;
 // Sends the message to all. This message will receive all 
 // processes on the Cybiko computer.
 Message_post_all( ptr_message, QF_ALL );
 ...

See also:: Message_post.

delivery_t Message_wait_delivery ( struct Message * ptr_message,

struct Flag * ptr_flag )

Waits until Message delivery is completed or flag is set.

Parameters:: ptr_message A pointer to the initialized Message object

ptr_flag A pointer to the synchronizing object, or 0

Returns:

Message delivery state

 #include <cybiko.h>
 #define MSG_TEST MSG_USER + 1
 ...
 struct module_t main_module;
 struct Flag delivery_flag;
 char partner_name[9];
 cyid_t partner_id;
 struct Message* ptr_message;
 ...
 init_module( &main_module );
 ...
 partner_id = select_game_partner( main_module.m_process,
 "Billiard",
 SGP_CYBIKO | SGP_HOT_SEAT,
 partner_name );
 if( partner_id )
 {
 ...
 ptr_message = Message_new( sizeof( struct Message ) );
 ptr_message->msgid = MSG_TEST;
 // Sends message to the "Billiard" application on the remote computer.
 Message_deliver( ptr_message, "Billiard", partner_id, 60*1000 );
 }
 Flag_ctor(&delivery_flag, "MessageMutex", TRUE);
 if( Message_wait_delivery( ptr_message, &delivery_flag ) == DL_SUCCESS )
 {
 TRACE( "Message was delivered successfully" );
 }
 Flag_dtor(&delivery_flag, LEAVE_MEMORY);
 ...

Member Data Documentation

cyid_t cyid_from

Cy ID of the sender device.

cyid_t cyid_to

Cy ID of the target device.

bool deleted

TRUE if the Message has been deleted from the queue.

char * dst_name

The name of the target process.

short msgid

ID of the Message.

struct Message * next

Pointer to the next Message in the queue.

long param[2]

Additional parameters for the Message.