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.