1 /*

     2 * Copyright (c) 1999 - 2001 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of the License "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description: 

    15 *

    16 */

    17 

    18 

    19 /*****************************************************************

    20 

    21   Subsystem Name: Messaging

    22   Version: V1.0

    23   Description:

    24     Provides interfaces to support messaging in a platform independent

    25   manner. 

    26 

    27   Messages are sent to a unique message Address. A NW_Msg_Address_t is used to 

    28   identify the receipient of a message. It is an opaque data type.  

    29   All receivers of messages must have a unique address.

    30 

    31     An address is a 1-way communicate channel. To receive a response from a 

    32   message the sender will also need to obtain a unique address of it's own 

    33   and listen for responses. 

    34 

    35   To send a message, the sender must first locate the reciever using the 

    36   function NW_Msg_LookupReceiver(Name). This id is then made part of 

    37   a NW_Msg_t structure. Also in that structure will be the senders address

    38   (assuming a response is desired), and the message itself.

    39 

    40     The RmMsgSend() function is called to send the message to the receiver.

    41   This function will return KBrsrSuccess or an error code.

    42 

    43      Messages are allocated by the sender and freed by the receiver.

    44 

    45 ******************************************************************/

    46 #ifndef NWX_MSG_API_H

    47 #define NWX_MSG_API_H

    48 

    49 /*

    50 **----------------------------------------------------------------------

    51 ** Preprocessor Macro Definitions

    52 **----------------------------------------------------------------------

    53 */

    54 #ifdef __cplusplus

    55 extern "C" {

    56 #endif

    57 

    58 /*

    59 **----------------------------------------------------------------------

    60 ** Includes

    61 **----------------------------------------------------------------------

    62 */

    63 #include "nwx_defs.h"

    64 #include "nwx_msg_types.h"

    65 #include "BrsrStatusCodes.h"

    66 

    67 /*

    68 **----------------------------------------------------------------------

    69 ** Type Definitions

    70 **----------------------------------------------------------------------

    71 */ 

    72 

    73 /* Messaging Data Types */

    74 typedef NW_Uint16 NW_Msg_Address_t;

    75 typedef NW_Uint16 NW_Msg_Type_t;

    76 typedef NW_Uint16 NW_Msg_RName_t;

    77 

    78 

    79 typedef struct _NW_Msg_t NW_Msg_t;

    80 

    81 struct _NW_Msg_t {

    82   NW_Msg_t          *next;    /* the next node */

    83   void              *data;    /* the content of the message */

    84   NW_Uint16         tid;      /* transaction ID */

    85   NW_Msg_Address_t  src;      /* source address */

    86   NW_Msg_Address_t  dest;     /* destination address */

    87   NW_Msg_Type_t     type;     /* set by the sender */

    88   TBrowserStatusCode       status;   /* additional status data (see status.h) */

    89 };

    90  

    91 /*

    92 **----------------------------------------------------------------------

    93 ** Global Function Declarations

    94 **----------------------------------------------------------------------

    95 */

    96 

    97 /* 1-time initialization function */

    98 TBrowserStatusCode NW_Msg_Initialize(const char* qName);

    99 

   100 /* create a new message */

   101 NW_Msg_t *NW_Msg_New(const NW_Uint16 tid, const NW_Msg_Address_t src,

   102                      const NW_Msg_Address_t dest, const NW_Msg_Type_t type);

   103 

   104 /* delete a message */

   105 void NW_Msg_Delete(NW_Msg_t *msg);

   106 

   107 /* send a message */

   108 TBrowserStatusCode NW_Msg_Send(NW_Msg_t *msg);

   109 

   110 /* return address of receiver */

   111 TBrowserStatusCode NW_Msg_LookupReceiverByName(const NW_Msg_RName_t name, 

   112                                         NW_Msg_Address_t *addr); 

   113 

   114 /* return address of receiver */

   115 TBrowserStatusCode NW_Msg_GetThisReceiver(NW_Msg_Address_t *addr);

   116 

   117 /* reinitialize the fields of a message */

   118 void NW_Msg_Reinit(NW_Msg_t *msg, const NW_Uint16 tid, const NW_Msg_Address_t dest,

   119                    const NW_Msg_Address_t src, const NW_Msg_Type_t type, 

   120                    const TBrowserStatusCode status, void *data );

   121 

   122 /* Send a message back to previous source */

   123 TBrowserStatusCode NW_Msg_Reply(NW_Msg_t *msg, const NW_Msg_Type_t type);

   124 

   125 /* Send a message on to another destination */

   126 TBrowserStatusCode NW_Msg_Forward(NW_Msg_t *msg, const NW_Msg_Address_t dest, 

   127                            const NW_Msg_Type_t type);

   128 

   129 

   130 #ifdef __cplusplus

   131 } /* extern "C" */

   132 #endif

   133 

   134 #endif  /* NWX_MSG_API_H */

   135 

   136