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
25extern "C" {
26#endif
27
28/** A message. */
29typedef struct MqMessage MqMessage;
30
31/** A destination to which messages can be sent. */
32typedef struct MqDestination MqDestination;
33
34/* Array of bytes. */
35typedef 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 */
43typedef void MqMessageListener(MqDestination* destination, MqMessage* message);
44
45/**
46 * Hears a destination close.
47 *
48 * @param destination that closed
49 */
50typedef 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 */
61MqMessage* mqCreateMessage(MqBytes header, MqBytes body,
62        MqDestination* replyTo);
63
64/** Sends a message to a destination. */
65void 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 */
77MqDestination* 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 */
89void* 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 */
96int mqIsDestinationLocal(MqDestination* destination);
97
98/**
99 * Increments the destination's reference count.
100 */
101void mqKeepDestination(MqDesintation* destination);
102
103/**
104 * Decrements the destination's reference count.
105 */
106void mqFreeDestination(MqDestination* desintation);
107
108/** Registry API. */
109
110/**
111 * Gets the destination bound to a name.
112 */
113MqDestination* mqGetDestination(char* name);
114
115/**
116 * Binds a destination to a name.
117 */
118void mqPutDestination(char* name, MqDestination* desintation);
119
120#ifdef __cplusplus
121}
122#endif
123
124#endif /* __MQ_H */
125