cutils/mq.h

   1 /*
   2  * Copyright (C) 2007 The Android Open Source Project
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 /**
  18  * IPC messaging library.
  19  */
  20
  21 #ifndef __MQ_H
  22 #define __MQ_H
  23
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif
  27
  28 /** A message. */
  29 typedef struct MqMessage MqMessage;
  30
  31 /** A destination to which messages can be sent. */
  32 typedef struct MqDestination MqDestination;
  33
  34 /* Array of bytes. */
  35 typedef struct MqBytes MqBytes;
  36
  37 /**
  38  * Hears messages.
  39  *
  40  * @param destination to which the message was sent
  41  * @param message the message to hear
  42  */
  43 typedef void MqMessageListener(MqDestination* destination, MqMessage* message);
  44
  45 /**
  46  * Hears a destination close.
  47  *
  48  * @param destination that closed
  49  */
  50 typedef void MqCloseListener(MqDestination* destination);
  51
  52 /** Message functions. */
  53
  54 /**
  55  * Creates a new Message.
  56  *
  57  * @param header as defined by user
  58  * @param body as defined by user
  59  * @param replyTo destination to which replies should be sent, NULL if none
  60  */
  61 MqMessage* mqCreateMessage(MqBytes header, MqBytes body,
  62         MqDestination* replyTo);
  63
  64 /** Sends a message to a destination. */
  65 void mqSendMessage(MqMessage* message, MqDestination* destination);
  66
  67 /** Destination functions. */
  68
  69 /**
  70  * Creates a new destination. Acquires a reference implicitly.
  71  *
  72  * @param messageListener function to call when a message is recieved
  73  * @param closeListener function to call when the destination closes
  74  * @param userData user-specific data to associate with the destination.
  75  *  Retrieve using mqGetDestinationUserData().
  76  */
  77 MqDestination* mqCreateDestination(MqMessageListener* messageListener,
  78         MqCloseListener* closeListener, void* userData);
  79
  80 /**
  81  * Gets user data which was associated with the given destination at
  82  * construction time.
  83  *
  84  * It is only valid to call this function in the same process that the
  85  * given destination was created in.
  86  * This function returns a null pointer if you call it on a destination
  87  * created in a remote process.
  88  */
  89 void* mqGetUserData(MqDestination* destination);
  90
  91 /**
  92  * Returns 1 if the destination was created in this process, or 0 if
  93  * the destination was created in a different process, in which case you have
  94  * a remote stub.
  95  */
  96 int mqIsDestinationLocal(MqDestination* destination);
  97
  98 /**
  99  * Increments the destination's reference count.
 100  */
 101 void mqKeepDestination(MqDesintation* destination);
 102
 103 /**
 104  * Decrements the destination's reference count.
 105  */
 106 void mqFreeDestination(MqDestination* desintation);
 107
 108 /** Registry API. */
 109
 110 /**
 111  * Gets the destination bound to a name.
 112  */
 113 MqDestination* mqGetDestination(char* name);
 114
 115 /**
 116  * Binds a destination to a name.
 117  */
 118 void mqPutDestination(char* name, MqDestination* desintation);
 119
 120 #ifdef __cplusplus
 121 }
 122 #endif
 123
 124 #endif /* __MQ_H */