2 // Open Service Platform
3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
5 // Licensed under the Apache License, Version 2.0 (the License);
6 // you may not use this file except in compliance with the License.
7 // You may obtain a copy of the License at
9 // http://www.apache.org/licenses/LICENSE-2.0
11 // Unless required by applicable law or agreed to in writing, software
12 // distributed under the License is distributed on an "AS IS" BASIS,
13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 // See the License for the specific language governing permissions and
15 // limitations under the License.
19 #ifndef __APPFW_MESSAGE_PORT_H__
20 #define __APPFW_MESSAGE_PORT_H__
29 * @brief Enumerations of error code for Application.
33 MESSAGEPORT_ERROR_NONE = 0, /**< Successful */
34 MESSAGEPORT_ERROR_IO_ERROR = -1, /**< Internal I/O error */
35 MESSAGEPORT_ERROR_OUT_OF_MEMORY = -2, /**< Out of memory */
36 MESSAGEPORT_ERROR_INVALID_PARAMETER = -3, /**< Invalid parameter */
37 MESSAGEPORT_ERROR_MESSAGEPORT_NOT_FOUND = -4, /**< The message port of the remote application is not found */
38 MESSAGEPORT_ERROR_CERTIFICATE_NOT_MATCH = -5, /**< The remote application is not signed with the same certificate */
39 MESSAGEPORT_ERROR_MAX_EXCEEDED = -6, /**< The size of message has exceeded the maximum limit */
40 } messageport_error_e;
44 * @brief Called when a message is received from the remote application.
46 * @param [in] id The message port id returned by messageport_register_local_port() or messageport_register_trusted_local_port()
47 * @param [in] remote_app_id The ID of the remote application which has sent this message
48 * @param [in] remote_port The name of the remote message port
49 * @param [in] trusted_message @c true if the trusted remote message port is ready to receive the response data
50 * @param [in] data the data passed from the remote application
51 * @remarks @a data must be released with bundle_free() by you
52 * @remark @a remote_app_id and @a remote_port will be set if the remote application sends a bidirectional message, otherwise they are NULL.
54 typedef void (*messageport_message_cb)(int id, const char* remote_app_id, const char* remote_port, bool trusted_message, bundle* data);
58 * @brief Registers the local message port.
60 * @param [in] local_port the name of the local message port
61 * @param [in] callback The callback function to be called when a message is received
62 * @return A message port id on success, otherwise a negative error value.
63 * @retval #MESSAGEPORT_ERROR_NONE Successful
64 * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
65 * @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
66 * @retval #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
68 int messageport_register_local_port(const char* local_port, messageport_message_cb callback);
71 * @brief Registers the trusted local message port.
73 * @param [in] local_port the name of the local message port
74 * @param [in] callback The callback function to be called when a message is received
75 * @return A message port id on success, otherwise a negative error value.
76 * @retval #MESSAGEPORT_ERROR_NONE Successful
77 * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
78 * @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
79 * @retval #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
81 int messageport_register_trusted_local_port(const char* local_port, messageport_message_cb callback);
85 * @brief Unregisters the local message port.
87 * @param [in] id The message port id returned by messageport_register_local_port() or messageport_register_trusted_local_port()
88 * @return 0 on success, otherwise a negative error value.
89 * @retval #MESSAGEPORT_ERROR_NONE Successful
90 * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
91 * @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
93 int messageport_unregister_local_port(int id);
96 * @brief Checks if the message port of a remote application is registered.
98 * @param [in] remote_app_id The ID of the remote application
99 * @param [in] remote_port the name of the remote message port
100 * @param [out] exist @c true if the message port of the remote application exists, otherwise @c false
101 * @return 0 on success, otherwise a negative error value.
102 * @retval #MESSAGEPORT_ERROR_NONE Successful
103 * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
104 * @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
105 * @retval #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
107 int messageport_check_remote_port(const char* remote_app_id, const char *remote_port, bool* exist);
110 * @brief Checks if the trusted message port of a remote application is registered.
112 * @param [in] remote_app_id The ID of the remote application
113 * @param [in] remote_port the name of the remote message port
114 * @param [out] exist @c true if the message port of the remote application exists, otherwise @c false
115 * @return 0 on success, otherwise a negative error value.
116 * @retval #MESSAGEPORT_ERROR_NONE Successful
117 * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
118 * @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
119 * @retval #MESSAGEPORT_ERROR_CERTIFICATE_NOT_MATCH The remote application is not signed with the same certificate
120 * @retval #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
122 int messageport_check_trusted_remote_port(const char* remote_app_id, const char *remote_port, bool* exist);
125 * @brief Sends a message to the message port of a remote application.
127 * @param [in] remote_app_id The ID of the remote application
128 * @param [in] remote_port the name of the remote message port
129 * @param [in] message the message to be passed to the remote application
130 * @return 0 on success, otherwise a negative error value.
131 * @retval #MESSAGEPORT_ERROR_NONE Successful
132 * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
133 * @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
134 * @retval #MESSAGEPORT_ERROR_MESSAGEPORT_NOT_FOUND The message port of the remote application is not found
135 * @retval #MESSAGEPORT_ERROR_MAX_EXCEEDED The size of message has exceeded the maximum limit
136 * @retval #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
139 * #include <message-port.h>
141 * bundle *b = bundle_create();
142 * bundle_add(b, "key1", "value1");
143 * bundle_add(b, "key2", "value2");
145 * int ret = messageport_send_message("0123456789.BasicApp", "BasicAppPort", b);
150 int messageport_send_message(const char* remote_app_id, const char* remote_port, bundle* message);
153 * @brief Sends a trusted message to the message port of a remote application.
155 * @param [in] remote_app_id The ID of the remote application
156 * @param [in] remote_port the name of the remote message port
157 * @param [in] message the message to be passed to the remote application
158 * @return 0 on success, otherwise a negative error value.
159 * @retval #MESSAGEPORT_ERROR_NONE Successful
160 * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
161 * @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
162 * @retval #MESSAGEPORT_ERROR_MESSAGEPORT_NOT_FOUND The message port of the remote application is not found
163 * @retval #MESSAGEPORT_ERROR_CERTIFICATE_NOT_MATCH The remote application is not signed with the same certificate
164 * @retval #MESSAGEPORT_ERROR_MAX_EXCEEDED The size of message has exceeded the maximum limit
165 * @retval #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
167 int messageport_send_trusted_message(const char* remote_app_id, const char* remote_port, bundle* message);
170 * @brief Sends a message to the message port of a remote application. This method is used for the bidirectional communication.
172 * @param [in] id The message port id returned by messageport_register_local_port() or messageport_register_trusted_local_port()
173 * @param [in] remote_app_id The ID of the remote application
174 * @param [in] remote_port the name of the remote message port
175 * @param [in] message the message to be passed to the remote application
176 * @return 0 on success, otherwise a negative error value.
177 * @retval #MESSAGEPORT_ERROR_NONE Successful
178 * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
179 * @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
180 * @retval #MESSAGEPORT_ERROR_MESSAGEPORT_NOT_FOUND The message port of the remote application is not found
181 * @retval #MESSAGEPORT_ERROR_MAX_EXCEEDED The size of message has exceeded the maximum limit
182 * @retval #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
185 * #include <message-port.h>
188 * OnMessageReceived(int id, const char* remote_app_id, const char* remote_port, bool trusted_port, bundle* data)
192 * int main(int argc, char *argv[])
194 * bundle *b = bundle_create();
195 * bundle_add(b, "key1", "value1");
196 * bundle_add(b, "key2", "value2");
198 * int id = messageport_register_local_port("HelloPort", OnMessageReceived);
200 * int ret = messageport_send_message(id, "0123456789.BasicApp", "BasicAppPort", b);
205 int messageport_send_bidirectional_message(int id, const char* remote_app_id, const char* remote_port, bundle* data);
208 * @brief Sends a trusted message to the message port of a remote application. This method is used for the bidirectional communication.
210 * @param [in] id The message port id returned by messageport_register_local_port() or messageport_register_trusted_local_port()
211 * @param [in] remote_app_id The ID of the remote application
212 * @param [in] remote_port the name of the remote message port
213 * @param [in] message the message to be passed to the remote application
214 * @return 0 on success, otherwise a negative error value.
215 * @retval #MESSAGEPORT_ERROR_NONE Successful
216 * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
217 * @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
218 * @retval #MESSAGEPORT_ERROR_MESSAGEPORT_NOT_FOUND The message port of the remote application is not found
219 * @retval #MESSAGEPORT_ERROR_CERTIFICATE_NOT_MATCH The remote application is not signed with the same certificate
220 * @retval #MESSAGEPORT_ERROR_MAX_EXCEEDED The size of message has exceeded the maximum limit
221 * @retval #MESSAGEPORT_ERROR_IO_ERROR Internal I/O error
223 int messageport_send_bidirectional_trusted_message(int id, const char* remote_app_id, const char* remote_port, bundle* data);
227 * @brief Gets the name of the local message port.
229 * @param [in] id The message port id returned by messageport_register_local_port() or messageport_register_trusted_local_port()
230 * @param [out] name The name of the local message port
231 * @return 0 on success, otherwise a negative error value.
232 * @retval #MESSAGEPORT_ERROR_NONE Successful
233 * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
234 * @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
235 * @remarks @a name must be released with free() by you
237 int messageport_get_local_port_name(int id, char **name);
240 * @brief Checks if the local message port is trusted.
242 * @param [in] id The message port id returned by messageport_register_local_port() or messageport_register_trusted_local_port()
243 * @param [out] @c true if the local message port is trusted
244 * @return 0 on success, otherwise a negative error value.
245 * @retval #MESSAGEPORT_ERROR_NONE Successful
246 * @retval #MESSAGEPORT_ERROR_INVALID_PARAMETER Invalid parameter
247 * @retval #MESSAGEPORT_ERROR_OUT_OF_MEMORY Out of memory
249 int messageport_check_trusted_local_port(int id, bool *trusted);
259 #endif /* __APPFW_MESSAGE_PORT_H__ */