2 * @copyright Copyright (c) 2016-2020 TOYOTA MOTOR CORPORATION.
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
19 * @brief \~english APIs to Open/Close and Send/Receive on message queues and shared memory.
22 /** @addtogroup BaseSystem
25 /** @addtogroup native_service
29 /** @addtogroup framework_unified
30 * @ingroup native_service
33 /** @addtogroup native
34 * @ingroup framework_unified
37 #ifndef __NATIVESERVICES_MESSAGE_CENTER_IF_H__ // NOLINT (build/header_guard)
38 #define __NATIVESERVICES_MESSAGE_CENTER_IF_H__
40 #include <native_service/frameworkunified_types.h>
41 #include <native_service/ns_shared_mem_if.h>
49 ////////////////////////////////////////////////////////////////////////////////////////////
50 /// \ingroup McOpenReceiver
51 /// \~english @par Brief
52 /// Opens a handle to a Receiver message queue.
53 /// \~english @param[in] name
54 /// PCSTR - name of the message queue you want to receiver messages on
55 /// \~english @retval Handle to a recevier's message queue (If INVALID_HANDLE is returned its an error)
56 /// \~english @par Preconditons
58 /// \~english @par Change of internal status
60 /// \~english @par Conditions of processing failure
61 /// - Size of message queue name string specified by argument(name) is larger then 20byte. [NULL]
62 /// - Message queue name specified by argument(name) is NULL. [NULL]
63 /// - Size of name normalised from argument(name) for message queue is larger then 15byte[16byte when starts with
65 /// - Failed to create(malloc) buffer to storage name normalised from argument(name) for message queue. [NULL]
66 /// - Failed to get(mq_open) message queue. [NULL]
67 /// - Failed to create(malloc) buffer to storage management information of message queue. [NULL]
68 /// \~english @par Detail
69 /// Create a message queue whose name is specified by argument, and return a handle for receiving message. \n
70 /// The message queue created in this API is used to receive message, but not to send message. \n
71 /// You can use message queue in McOpenSender to send message.
72 /// \~english @par Classification
74 /// \~english @par Type
76 /// \~english @see McOpenSender, McReceive, McClose
77 ////////////////////////////////////////////////////////////////////////////////////////////
78 HANDLE McOpenReceiver(PCSTR name);
80 ////////////////////////////////////////////////////////////////////////////////////////////
81 /// \ingroup McOpenReceiverNotBlocked
82 /// \~english @par Brief
83 /// Opens a handle to a Receiver message queue. Operations on this queue are
84 /// non-blocking if queue is empty or full.
85 /// \~english @param[in] name
86 /// PCSTR - name of the message queue you want to receiver messages on
87 /// \~english @retval Handle to a recevier's message queue (If INVALID_HANDLE is returned its an error)
88 /// \~english @par Preconditons
90 /// \~english @par Change of internal status
92 /// \~english @par Conditions of processing failure
93 /// - Size of message queue name string specified by argument(name) is larger then 20byte. [NULL]
94 /// - Message queue name specified by argument(name) is NULL. [NULL]
95 /// - Size of name normalised from argument(name) for message queue is larger then 15byte[16byte when starts with
97 /// - Failed to create(malloc) buffer to storage name normalised from argument(name) for message queue. [NULL]
98 /// - Failed to get(mq_open) message queue. [NULL]
99 /// - Failed to create(malloc) buffer to storage management information of message queue. [NULL]
100 /// \~english @par Detail
101 /// Create a message queue whose name is specified by argument, and return a handle for receiving message. \n
102 /// The message queue created in this API is used to receive message, but not to send message. \n
103 /// You can use message queue in McOpenSender to send message.
104 /// \~english @par Classification
106 /// \~english @par Type
108 /// \~english @see McOpenSender, McReceive, McClose, McOpenSenderNotBlocked
109 ////////////////////////////////////////////////////////////////////////////////////////////
110 HANDLE McOpenReceiverNotBlocked(PCSTR name);
112 ////////////////////////////////////////////////////////////////////////////////////////////
113 /// \ingroup McOpenSyncReceiver
114 /// \~english @par Brief
115 /// Opens a handle to a response Receiver message queue.
116 /// \~english @param[in] name
117 /// PCSTR - name of the message queue you want to receiver messages on
118 /// \~english @retval Handle to a recevier's message queue (If INVALID_HANDLE is returned its an error)
119 /// \~english @par Preconditons
121 /// \~english @par Change of internal status
123 /// \~english @par Conditions of processing failure
124 /// - Size of message queue name string specified by argument(name) is larger then 20byte. [NULL]
125 /// - Message queue name specified by argument(name) is NULL. [NULL]
126 /// - Size of name normalised from argument(name) for message queue(don't start with "/") is larger then 19byte.
128 /// - Size of name normalised from argument(name) for message queue(start with "/") is larger then 20byte. [NULL]
129 /// - Failed to create(malloc) buffer to storage name normalised from argument(name) for message queue. [NULL]
130 /// - Failed to get(mq_open) message queue. [NULL]
131 /// - Failed to create(malloc) buffer to storage management information of message queue. [NULL]
132 /// \~english @par Detail
133 /// Create a message queue whose name is specified by argument, and return a handle for receiving message
134 /// by synchronous communication.
136 /// This API provides the inter-process communication function by the message queue for the application
137 /// which does not use the inter-process communication by NS Framework Dispatcher.
139 /// When the application used the message queue acquired by this API, note the following.
140 /// - Use McCreateInvokerName to obtain the receive message queue handle to be passed to the parameter name.
141 /// - It can not be used transmission because it is for reception.
142 /// McOpenSender must be used for the message queue trasmission.
143 /// - Cannot be used other than for waiting for response during synchronous communication.
144 /// (because the maxmum number of messages in the queue is specified as 2)
145 /// - When a message queue name (name) that has not been normalized is specified, transmission falis unless 18 byte are specified.
146 /// \~english @par Classification
148 /// \~english @par Type
150 /// \~english @see McCreateInvokerName, McInvokeSync, McClose
151 ////////////////////////////////////////////////////////////////////////////////////////////
152 HANDLE McOpenSyncReceiver(PCSTR name);
155 ////////////////////////////////////////////////////////////////////////////////////////////
156 /// \ingroup McOpenSender
157 /// \~english @par Brief
158 /// The opens a handle for sending messages to another message queue.
159 /// \~english @param[in] name
160 /// PCSTR - name of the message queue you want to send messages too
161 /// \~english @retval Handle for sending messages to a queue (If INVALID_HANDLE is returned its an error)
162 /// \~english @par Preconditons
164 /// \~english @par Change of internal status
166 /// \~english @par Conditions of processing failure
167 /// - Size of message queue name string specified by argument(name) is larger then 20byte. [NULL]
168 /// - Message queue name specified by argument(name) is NULL. [NULL]
169 /// - Size of name normalised from argument(name) for message queue is larger then 15byte[16byte when starts with
171 /// - Failed to create(malloc) buffer to storage name normalised from argument(name) for message queue. [NULL]
172 /// - Failed to get(mq_open) message queue. [NULL]
173 /// - Failed to create(malloc) buffer to storage management information of message queue. [NULL]
174 /// \~english @par Detail
175 /// Create a message queue whose name is specified by argument, and return a handle for sending message. \n
176 /// The message queue created in this API is used to send message, but not to receive message. \n
177 /// You can use message queue in McOpenReceiver to receive message.
179 /// This API provides the inter-process communication function by the message queue for the application
180 /// which does not use the inter-process communication by NS Framework Dispatcher.
181 /// \~english @par Classification
183 /// \~english @par Type
185 /// \~english @see McOpenReceiver, McSend, McClose
186 ////////////////////////////////////////////////////////////////////////////////////////////
187 HANDLE McOpenSender(PCSTR name);
189 ////////////////////////////////////////////////////////////////////////////////////////////
190 /// The opens a handle for sending messages to another message queue.
191 /// operations on this queue are non-blocking if queue is empty or full.
194 /// PCSTR - name of the message queue you want to send messages too
197 /// handle - for sending messages to a queue (If INVALID_HANDLE is returned its an error)
198 ////////////////////////////////////////////////////////////////////////////////////////////
199 HANDLE McOpenSenderNotBlocked(PCSTR name);
201 ////////////////////////////////////////////////////////////////////////////////////////////
202 /// \ingroup McOpenSyncSender
203 /// \~english @par Brief
204 /// The opens a handle for sending responce to another message queue.
205 /// \~english @param[in] name
206 /// PCSTR - name of the message queue you want to send messages too
207 /// \~english @retval Handle for sending response to a queue (If INVALID_HANDLE is returned its an error)
208 /// \~english @par Preconditons
210 /// \~english @par Change of internal status
212 /// \~english @par Conditions of processing failure
213 /// - Size of message queue name string specified by argument(name) is larger then 20byte. [NULL]
214 /// - Message queue name specified by argument(name) is NULL. [NULL]
215 /// - Size of name normalised from argument(name) for message queue(don't start with "/") is larger then 19byte.
217 /// - Size of name normalised from argument(name) for message queue(start with "/") is larger then 20byte. [NULL]
218 /// - Failed to create(malloc) buffer to storage name normalised from argument(name) for message queue. [NULL]
219 /// - Failed to get(mq_open) message queue. [NULL]
220 /// - Failed to create(malloc) buffer to storage management information of message queue. [NULL]
221 /// \~english @par Detail
222 /// Create a message queue whose name is specified by argument, and return a handle for sending message. \n
223 /// The message queue created in this API is used to send message, but not to receive message. \n
224 /// You can use message queue in McOpenReceiver to receive message.
226 /// This API provides the inter-process communication function by the message queue for the application
227 /// which does not use the inter-process communication by NS Framework Dispatcher.
228 /// \~english @par Classification
230 /// \~english @par Type
232 /// \~english @see McOpenReceiver, McSend, McClose
233 ////////////////////////////////////////////////////////////////////////////////////////////
234 HANDLE McOpenSyncSender(PCSTR name);
236 /////////////////////////////////////////
238 HANDLE McOpenSenderChild(PCSTR name, pthread_t childid);
239 /////////////////////////////////////////
241 /////////////////////////////////////////
242 EFrameworkunifiedStatus McJoinChild(HANDLE hChildApp);
243 /////////////////////////////////////////
245 /////////////////////////////////////////
246 EFrameworkunifiedStatus McGetChildThreadPriority(HANDLE hChildApp, PSI_32 threadPrio);
247 /////////////////////////////////////////
249 ////////////////////////////////////////////////////////////////////////////////////////////
250 /// \ingroup McReceive
251 /// \~english @par Brief
252 /// Retrieves data from a message queue.
253 /// \~english @param[in] hMessage
254 /// HANDLE - handle to the recvMessage, McOpenRecevier
255 /// \~english @param[out] source
256 /// PSTR - app that sent this message
257 /// \~english @param[out] cmd
258 /// UI_32* - command message that has been received.
259 /// \~english @param[in] length
260 /// UI_32 - length of the data buffer provided
261 /// \~english @param[out] data
262 /// PVOID - pointer to the data to be received
263 /// \~english @retval EFrameworkunifiedStatus indicates if the message was sent successfully
264 /// \~english @retval eFrameworkunifiedStatusOK Success
265 /// \~english @retval eFrameworkunifiedStatusInvldHandle - Invalid handle
266 /// \~english @retval eFrameworkunifiedStatusInvldBuf - Invalid buffer
267 /// \~english @retval eFrameworkunifiedStatusInvldQName - Invalid message queue name
268 /// \~english @retval eFrameworkunifiedStatusInvldParam - Invalid parameter
269 /// \~english @retval eFrameworkunifiedStatusErrNoEBADF - Invalid File-Descriptor
270 /// \~english @retval eFrameworkunifiedStatusErrNoEINTR - An interrupt is generated by the system call (signal)
271 /// \~english @retval eFrameworkunifiedStatusInvldBufSize - Invalid buffer-size
272 /// \~english @retval eFrameworkunifiedStatusFail - Invalid handle of message queue for receiving message
273 /// \~english @par Preconditons
274 /// Message queue(McOpenReceiver etc.) for receiving message is created.
275 /// \~english @par Change of internal status
277 /// \~english @par Conditions of processing failure
278 /// - Data buffer specified by argument(data) for receiving message is NULL. [eFrameworkunifiedStatusInvldBuf]
279 /// - Size of data buffer specified by argument(length) for receiving message is 0. [eFrameworkunifiedStatusInvldBuf]
280 /// - Buffer to storage application name specified by argument(source) for sending message is NULL.
281 /// [eFrameworkunifiedStatusInvldQName]
282 /// - Buffer to storage commond ID of protocol on the service specified by argument(cmd) is NULL.
283 /// [eFrameworkunifiedStatusInvldParam]
284 /// - Size of application name of sender getted from received message is lager then 20byte. [eFrameworkunifiedStatusInvldBuf]
285 /// - Handle specified by argument(hMessage) is NULL. [eFrameworkunifiedStatusInvldHandle]
286 /// - HANDLE specified by argument(hMessage) is not appropriate(which is invalid). [eFrameworkunifiedStatusFail]
287 /// - Message queue type of handle specified by argument(hMessage) is not receiving type. [eFrameworkunifiedStatusFail]
288 /// - File descriptor for receiving message is invalid. [eFrameworkunifiedStatusErrNoEBADF]
289 /// - An interrupt is generated by the system call (signal) when receiving message. [eFrameworkunifiedStatusErrNoEINTR]
290 /// - Size of buffer for receiving message is invalid. [eFrameworkunifiedStatusInvldBufSize]
291 /// \~english @par Detail
292 /// Receives data from message queue specified by argument.
293 /// Sets application of sender(source), commond ID of protocol on the service(cmd), receiving data(data), and
295 /// It will block until getting message from message queue.
297 /// This API provides the inter-process communication function by the message queue for the application
298 /// which does not use the inter-process communication by NS Framework Dispatcher.
300 /// Since data is exchanged only in the message queue, the data size that can be received is up to 4096 bytes.
302 /// The caller must guarantee the allocation of the area for the receive data buffer
303 /// and the consistency of the sizes set in the arguments.
304 /// \~english @par Classification
306 /// \~english @par Type
308 /// \~english @see McOpenReceiver, McSend
309 ////////////////////////////////////////////////////////////////////////////////////////////
310 EFrameworkunifiedStatus McReceive(HANDLE hMessage, PSTR source, UI_32 *cmd, UI_32 length, PVOID data);
312 ////////////////////////////////////////////////////////////////////////////////////////////
313 /// \ingroup McReceiveWithSession
314 /// \~english @par Brief
315 /// Retrieves data from a message queue.
316 /// \~english @param[in] hMessage
317 /// HANDLE - handle to the recvMessage, McOpenRecevier
318 /// \~english @param[out] source
319 /// PSTR - app that sent this message
320 /// \~english @param[out] cmd
321 /// UI_32* - command message that has been received.
322 /// \~english @param[out] sessionid
323 /// UI_32* - Session ID
324 /// \~english @param[in] length
325 /// UI_32 - length of the data buffer provided
326 /// \~english @param[out] data
327 /// PVOID - pointer to the data to be received
328 /// \~english @retval EFrameworkunifiedStatus indicates if the message was sent successfully
329 /// \~english @retval eFrameworkunifiedStatusOK Success
330 /// \~english @retval eFrameworkunifiedStatusInvldHandle - Invalid handle
331 /// \~english @retval eFrameworkunifiedStatusInvldBuf - Invalid buffer
332 /// \~english @retval eFrameworkunifiedStatusInvldQName - Invalid message queue name
333 /// \~english @retval eFrameworkunifiedStatusInvldParam - Invalid parameter
334 /// \~english @retval eFrameworkunifiedStatusErrNoEBADF - Invalid File-Descriptor
335 /// \~english @retval eFrameworkunifiedStatusErrNoEINTR - An interrupt is generated by the system call (signal)
336 /// \~english @retval eFrameworkunifiedStatusInvldBufSize - Invalid buffer-size
337 /// \~english @retval eFrameworkunifiedStatusFail - Invalid handle of message queue for receiving message
338 /// \~english @par Preconditons
339 /// Message queue(McOpenReceiver etc.) for receiving message is created.
340 /// \~english @par Change of internal status
342 /// \~english @par Conditions of processing failure
343 /// - Buffer to storage session ID specified by argument(sessionid) is NULL. [eFrameworkunifiedStatusInvldParam]
344 /// - Buffer to storage handle of message queue specified by argument(hMessage) is NULL. [eFrameworkunifiedStatusInvldHandle]
345 /// - Data buffer specified by argument(data) for receiving message is NULL. [eFrameworkunifiedStatusInvldBuf]
346 /// - Size of data buffer specified by argument(length) for receiving message is 0. [eFrameworkunifiedStatusInvldBuf]
347 /// - Buffer to storage application name specified by argument(source) for sending message is NULL.
348 /// [eFrameworkunifiedStatusInvldQName]
349 /// - Buffer to storage commond ID of protocol on the service specified by argument(cmd) is NULL.
350 /// [eFrameworkunifiedStatusInvldParam]
351 /// - Size of application name of sender getted from received message is lager then 20byte. [eFrameworkunifiedStatusInvldBuf]
352 /// - Handle specified by argument(hMessage) is NULL. [eFrameworkunifiedStatusInvldHandle]
353 /// - HANDLE specified by argument(hMessage) is not appropriate(which is invalid). [eFrameworkunifiedStatusFail]
354 /// - Message queue type of handle specified by argument(hMessage) is not receiving type. [eFrameworkunifiedStatusFail]
355 /// - File descriptor for receiving message is invalid. [eFrameworkunifiedStatusErrNoEBADF]
356 /// - An interrupt is generated by the system call (signal) when receiving message. [eFrameworkunifiedStatusErrNoEINTR]
357 /// - Size of buffer for receiving message is invalid. [eFrameworkunifiedStatusInvldBufSize]
358 /// \~english @par Detail
359 /// Receives data from message queue specified by argument.Sets application of sender(source),
360 /// commond ID of protocol on the service(cmd), receiving data(data), session id(sessionid), and return.
361 /// It will block until getting message from message queue.
363 /// This API provides the inter-process communication function by the message queue for the application
364 /// which does not use the inter-process communication by NS Framework Dispatcher.
366 /// The caller must guarantee the allocation of the area for the receive data buffer
367 /// and the consistency of the sizes set in the arguments.
368 /// \~english @par Classification
370 /// \~english @par Type
372 /// \~english @see McOpenReceiver, McSendWithSession
373 ////////////////////////////////////////////////////////////////////////////////////////////
374 EFrameworkunifiedStatus McReceiveWithSession(HANDLE hMessage, PSTR source, UI_32 *cmd, UI_32 *sessionid,
375 UI_32 length, PVOID data);
377 ////////////////////////////////////////////////////////////////////////////////////////////
378 /// \ingroup McGetLength
379 /// \~english @par Brief
380 /// Get the length of data that needs to be retrieved.
381 /// \~english @param[in] data
382 /// PVOID - pointer to the data was received from the McReceive Call
383 /// \~english @retval UI_32 indicates the number of bytes that in the message
385 /// if return is 0 or less then invalid data was passed.
386 /// \~english @par Preconditons
387 /// - Message is received by McReceive and so on.
388 /// \~english @par Change of internal status
390 /// \~english @par Conditions of processing failure
391 /// - Data of received message(data) is NULL. [0]
392 /// \~english @par Detail
393 /// Return message data length specified by the header of received message. \n
394 /// Use this data length as the buffer size specified by McGetDataOfSize.
396 /// This API does not distinguish between error and no data.
398 /// The parameter data of this API must be the data obtained from the message queue by McReceive, etc.
399 /// (Since the data obtained from the message queue incudes header information,
400 /// this API acquires necessary iformation from the header)
401 /// \~english @par Classification
403 /// \~english @par Type
405 /// \~english @see McReceive, McReceiveWithSession, McGetDataOfSize
406 ////////////////////////////////////////////////////////////////////////////////////////////
407 UI_32 McGetLength(PVOID data);
409 ////////////////////////////////////////////////////////////////////////////////////////////
410 /// \ingroup McGetDataPointer
411 /// \~english @par Brief
412 /// Get header address of data from received message.
413 /// \~english @param[in] data
414 /// PVOID - received message data
415 /// \~english @retval PVOID - data address of received message
416 /// \~english @par Preconditons
417 /// Message is received by McReceive and so on.
418 /// \~english @par Change of internal status
420 /// \~english @par Conditions of processing failure
421 /// - Data of received message(data) is NULL. [NULL]
422 /// \~english @par Detail
423 /// Get header address of data from received message excepting the header and system information.
425 /// Please note the following points when using this API for application.
426 /// - Since the pointer acquired by this API is part of the received message passed as an argument to this API,
427 /// the pointer must not be released by specifying he address acquired by this API.
428 /// - The parameter data of this API must be the data obtained from the message queue by McReceive, etc.
429 /// (Since the data obtained from the message queue incudes header information,
430 /// this API acquires necessary iformation from the header)
431 /// - When the next message is received, the internally held data is discarded.
432 /// \~english @par Classification
434 /// \~english @par Type
436 /// \~english @see McReceive, McReceiveWithSession, McGetDataOfSize
437 ////////////////////////////////////////////////////////////////////////////////////////////
438 PVOID McGetDataPointer(PVOID data);
440 ////////////////////////////////////////////////////////////////////////////////////////////
441 /// \ingroup McGetDataOfSize
442 /// \~english @par Brief
443 /// Get the message data, this may be from a queue or shared memory where the maximum
444 /// size of the data should not exceed the maximum size passed in.
445 /// And deletes the data if it is stored in shared memory.
446 /// \~english @param[in] data
447 /// PVOID - pointer to the data was received from the McReceive Call
448 /// \~english @param[in] to
449 /// PVOID - pointer to the data to be received
450 /// \~english @param[in] uiSize
451 /// UI_32 - maximum size of the buffer to which the received data is copied
452 /// \~english @retval EFrameworkunifiedStatus indicates if the message was sent successfully
453 /// \~english @retval eFrameworkunifiedStatusOK - success
454 /// \~english @retval eFrameworkunifiedStatusInvldBuf - invalid buffer
455 /// \~english @retval eFrameworkunifiedStatusInvldHandle - invalid handle
456 /// \~english @retval eFrameworkunifiedStatusInvldHndlType - invalid handle type
457 /// \~english @retval eFrameworkunifiedStatusInvldBufSize - invalid buffer size
458 /// \~english @retval eFrameworkunifiedStatusErrOther - invalid shared memory ID specified by received message
459 /// \~english @par Preconditons
460 /// - Message is received by McReceive and so on.
461 /// \~english @par Change of internal status
463 /// \~english @par Conditions of processing failure
464 /// - Size specified by argument(uiSize) is smaller then size of received message data(data).
465 /// [eFrameworkunifiedStatusInvldBufSize]
466 /// - Data of received message(data) is NULL. [eFrameworkunifiedStatusInvldBuf]
467 /// - Pointer to buffer(to) which is used to storage data getted from message is NULL. [eFrameworkunifiedStatusInvldBuf]
468 /// - Received message data specified by argument(data) is invalid. [eFrameworkunifiedStatusInvldHndlType]
469 /// - Failed to access(shm_open/fstat/mmap) the shared memory of received message data(data).
470 /// [eFrameworkunifiedStatusErrOther]
471 /// - Shared memory ID specified by received message is invalid. [FrameworkunifiedStatusErrOther]
472 /// \~english @par Detail
473 /// Get data from received message excepting the header and system information.
474 /// Delete data storaged in shared memory after getting the data successfully.
476 /// Please note the following points when using this API for application.
477 /// - In the case where he received message data becomes 0byte, there is no need to call this API,
478 /// and be careful not to allocate the memory for the received message data by 0byte.
479 /// - Error details related to shared memory access canno be detected.
480 /// \~english @par Classification
482 /// \~english @par Type
484 /// \~english @see McGetLength
485 ////////////////////////////////////////////////////////////////////////////////////////////
486 EFrameworkunifiedStatus McGetDataOfSize(PVOID data, PVOID to, UI_32 uiSize);
488 ////////////////////////////////////////////////////////////////////////////////////////////
489 /// \ingroup McGetDataOfSizeWithSMRetain
490 /// \~english @par Brief
491 /// Get the message data, this may be from a queue or shared memory where the maximum
492 /// size of the data should not exceed the maximum size passed in.
493 /// Does not delete the data if it is stored in shared memory.
494 /// \~english @param[in] data
495 /// PVOID - pointer to the data was received from the McReceive Call
496 /// \~english @param[in] to
497 /// PVOID - pointer to the data to be received
498 /// \~english @param[in] uiSize
499 /// UI_32 - maximum size of the buffer to which the received data is copied
500 /// \~english @retval EFrameworkunifiedStatus indicates if the message was sent successfully
501 /// \~english @retval eFrameworkunifiedStatusOK - success
502 /// \~english @retval eFrameworkunifiedStatusInvldBuf - invalid buffer
503 /// \~english @retval eFrameworkunifiedStatusInvldHandle - invalid handle
504 /// \~english @retval eFrameworkunifiedStatusInvldHndlType - invalid handle type
505 /// \~english @retval eFrameworkunifiedStatusInvldBufSize - invalid buffer size
506 /// \~english @retval eFrameworkunifiedStatusErrOther - invalid shared memory ID specified by received message
507 /// \~english @par Preconditons
508 /// - Message is received by McReceive and so on.
509 /// \~english @par Change of internal status
511 /// \~english @par Conditions of processing failure
512 /// - Size specified by argument(uiSize) is smaller then size of received message data(data).
513 /// [eFrameworkunifiedStatusInvldBufSize]
514 /// - Data of received message(data) is NULL. [eFrameworkunifiedStatusInvldBuf]
515 /// - Pointer to buffer(to) which is used to storage data getted from message is NULL. [eFrameworkunifiedStatusInvldBuf]
516 /// - Received message data specified by argument(data) is invalid. [eFrameworkunifiedStatusInvldHndlType]
517 /// - Failed to access(shm_open/fstat/mmap) the shared memory of received message data(data).
518 /// [eFrameworkunifiedStatusErrOther]
519 /// - Shared memory ID specified by received message is invalid. [FrameworkunifiedStatusErrOther]
520 /// \~english @par Detail
521 /// Get data from received message excepting the header and system information.
522 /// Does not delete data storaged in shared memory after getting the data successfully.
524 /// Please note the following points when using this API for application.
525 /// - In the case where he received message data becomes 0byte, there is no need to call this API,
526 /// and be careful not to allocate the memory for the received message data by 0byte.
527 /// - Error details related to shared memory access canno be detected.
528 /// \~english @par Classification
530 /// \~english @par Type
534 ////////////////////////////////////////////////////////////////////////////////////////////
535 EFrameworkunifiedStatus McGetDataOfSizeWithSMRetain(PVOID data, PVOID to, UI_32 uiSize);
537 ////////////////////////////////////////////////////////////////////////////////////////////
538 /// \ingroup McGetSysInfoData
539 /// \~english @par Brief
540 /// Gets the data from system info buffer from message header.
541 /// \~english @param[in] data
542 /// PVOID - pointer to the data was received from the McReceive Call
543 /// \~english @param[out] to
544 /// PVOID - pointer to the data to be received
545 /// \~english @retval EFrameworkunifiedStatus indicates if the close was successfully
546 /// \~english @retval eFrameworkunifiedStatusOK Success
547 /// \~english @retval eFrameworkunifiedStatusInvldBuf - Invalid buffer
548 /// \~english @retval eFrameworkunifiedStatusInvldHandle - Invalid handle
549 /// \~english @par Preconditons
550 /// Message is received by McReceive and so on.
551 /// \~english @par Change of internal status
553 /// \~english @par Conditions of processing failure
554 /// - Data of received message(data) is NULL. [eFrameworkunifiedStatusInvldBuf]
555 /// - Pointer to buffer(to) which is used to storage system info getted from message is NULL. [eFrameworkunifiedStatusInvldBuf]
556 /// - Received message data specified by argument(data) is invalid. [eFrameworkunifiedStatusInvldHndlType]
557 /// \~english @par Detail
558 /// Gets system info from received message, and set argument(to) with it. \n
559 /// If there is no system info in received message,and set argument(to) with "\0".
561 /// Please note the following points when using this API for application.
562 /// - The parameter data of this API must be the data obtained from the message queue by McReceive, etc.
563 /// (Since the data obtained from the message queue incudes header information,
564 /// this API acquires necessary iformation from the header)
565 /// - Since the system information is 64 bytes (including the null character), the area of 64 byte must be allocated in the argument to fo this API.
566 /// \~english @par Classification
568 /// \~english @par Type
570 /// \~english @see McReceive, McReceiveWithSession
571 ////////////////////////////////////////////////////////////////////////////////////////////
572 EFrameworkunifiedStatus McGetSysInfoData(PVOID data, PVOID to);
574 ////////////////////////////////////////////////////////////////////////////////////////////
575 /// \ingroup McClearData
576 /// \~english @par Brief
577 /// Clears the data that may be pending for the a message in shared memory.
578 /// \~english @param[in] data
579 /// PVOID - pointer to the data was received from the McReceive Call
580 /// \~english @retval EFrameworkunifiedStatus indicates if the data was clear successfully
581 /// \~english @retval eFrameworkunifiedStatusOK - success
582 /// \~english @retval eFrameworkunifiedStatusInvldBuf - invalid buffer
583 /// \~english @retval eFrameworkunifiedStatusInvldParam - invalid parameter
584 /// \~english @retval eFrameworkunifiedStatusInvldID - invalid ID
585 /// \~english @retval eFrameworkunifiedStatusFail - other errors
586 /// \~english @par Preconditons
587 /// - Message is received by McReceive and so on.
588 /// \~english @par Change of internal status
590 /// \~english @par Conditions of processing failure
591 /// - Data of received message(data) is NULL. [eFrameworkunifiedStatusInvldBuf]
592 /// - Received message data specified by argument(data) is invalid. [eFrameworkunifiedStatusInvldParam]
593 /// - Shared memory ID in received message is invalid. [eFrameworkunifiedStatusInvldParam]
594 /// - Shared memory specified by ID in received message does not exist. [eFrameworkunifiedStatusInvldID]
595 /// - Failed to delete shared memory specified by ID in received message. [eFrameworkunifiedStatusFail]
596 /// \~english @par Detail
597 /// Delete data from received message.
598 /// And delete the received message data if it is stored in shared memory.
599 /// \~english @par Classification
601 /// \~english @par Type
603 /// \~english @see McReceive, McReceiveWithSession
604 ////////////////////////////////////////////////////////////////////////////////////////////
605 EFrameworkunifiedStatus McClearData(PVOID data);
607 ////////////////////////////////////////////////////////////////////////////////////////////
609 /// \~english @par Brief
610 /// Sends data to a message queue.
611 /// \~english @param[in] hMessage
612 /// HANDLE - handle to the send message queue, McOpenSender
613 /// \~english @param[in] source
614 /// PCSTR - app (You) the sender
615 /// \~english @param[in] cmd
616 /// UI_32 - command id aka the message that's being sent
617 /// \~english @param[in] length
618 /// UI_32 - length of the data buffer provided
619 /// \~english @param[in] data
620 /// PCVOID - pointer to the data to be sent
621 /// \~english @retval EFrameworkunifiedStatus indicates if the message was sent successfully
622 /// \~english @retval eFrameworkunifiedStatusOK - Success
623 /// \~english @retval eFrameworkunifiedStatusNullPointer - NULL pointer specified
624 /// \~english @retval eFrameworkunifiedStatusInvldHandle - Invalid handle
625 /// \~english @retval eFrameworkunifiedStatusInvldHndlType - Invalid type of handle
626 /// \~english @retval eFrameworkunifiedStatusInvldQName - Illegal Message Queue name
627 /// \~english @retval eFrameworkunifiedStatusMsgQFull - Message queue is full
628 /// \~english @retval eFrameworkunifiedStatusErrNoEBADF I- nvalid File-Descriptor
629 /// \~english @retval eFrameworkunifiedStatusErrNoEINTR - An interrupt is generated by the system call (signal)
630 /// \~english @retval eFrameworkunifiedStatusInvldBufSize - Invalid buffer-size
631 /// \~english @retval eFrameworkunifiedStatusFail - Some sort of error occurred
632 /// \~english @retval eFrameworkunifiedStatusErrOther - other errors(Failed to open/allocate shared memory)
633 /// \~english @retval eFrameworkunifiedStatusInvldParam - Invalid parameter
634 /// \~english @par Preconditons
635 /// - Message queue(McOpenSender) for sending message is created.
636 /// \~english @par Change of internal status
638 /// \~english @par Conditions of processing failure
639 /// - Message queue name of HANDLE specified in the argument (hService) is NULL. [eFrameworkunifiedStatusInvldHandle]
640 /// - Message queue name of HANDLE specified in the argument (hService) exceeds 20byte. [eFrameworkunifiedStatusInvldHandle]
641 /// - Message queue HANDLE in HANDLE specified in the argument (hService) is NULL. [eFrameworkunifiedStatusInvldHandle]
642 /// - HANDLE specified in the argument message queue HANDLE in (hService) is not appropriate (which is invalid).
643 /// [eFrameworkunifiedStatusInvldHandle]
644 /// - Application name of sender specified in the argument (source) is NULL. [eFrameworkunifiedStatusInvldQName]
645 /// - Application name of sender specified in the argument (source) exceeds 20byte. [eFrameworkunifiedStatusInvldQName]
646 /// - Sender data does not match sender data size(size is larger then 0, and data is NULL). [eFrameworkunifiedStatusInvldBuf]
647 /// - Message queue type of handle specified by argument(hMessage) is not sending type. [eFrameworkunifiedStatusInvldHndlType]
648 /// - Message queue is full. [eFrameworkunifiedStatusMsgQFull]
649 /// - File descriptor for sending message is invalid. [eFrameworkunifiedStatusErrNoEBADF]
650 /// - An interrupt is generated by the system call (signal) when sending message. [eFrameworkunifiedStatusErrNoEINTR]
651 /// - Size of buffer for sending message is invalid. [eFrameworkunifiedStatusInvldBufSize]
652 /// - Some errors occur, when sending message. [eFrameworkunifiedStatusFail]
653 /// - Failed to access(shm_open/ftruncate/mmap) the shared memory for sending message data. [eFrameworkunifiedStatusErrOther]
654 /// - Sending data size specified in the argument (length) is out of range. [eFrameworkunifiedStatusInvldParam]
655 /// \~english @par Detail
656 /// It is an asynchronous API. It provides function to send message by message queue. \n
657 /// Message queue name created by McOpenSender is the sender.
659 /// This API provides the inter-process communication function by the message queue for the application
660 /// which does not use the inter-process communication by NS Framework Dispatcher.
662 /// Command ID must be within the range PROTOCOL_FRAMEWORKUNIFIED_BASE_CMD(0x10) to PROTOCOL_FRAMEWORKUNIFIED_MAX_CMD(0xFFFFFFF0).
663 /// Even if a command ID out of range is specified, a message is sent by the command ID (no erro occurs).
664 /// Command ID out of range are resered ID used for session connection, etc.
666 /// Please note the following points when using this API for application.
667 /// - The maximum transmission data size (ength) described above is a theoretical value,
668 /// and the maximum actually usable data size depends on the environment requirements.\n
669 /// The maximum value is the upper limit of the type (UNIT_MAX) minus the following size.\n
670 /// Message header section \n
671 /// - Operation cannot be guaranteed when the size of the allocated area indicated by the address
672 /// of the pointer (data) to the data buffer does not match the size specified by the size of the data buffer (length).
673 /// \~english @par Classification
675 /// \~english @par Type
677 /// \~english @see McOpenSender, McSendWithSession, McReceive
678 ////////////////////////////////////////////////////////////////////////////////////////////
679 EFrameworkunifiedStatus McSend(HANDLE hMessage, PCSTR source, UI_32 cmd, UI_32 length, PCVOID data);
681 //////////////////////////////////////////////////////////////////////////////////////////////
682 /// \ingroup McSendWithSession
683 /// \~english @par Brief
684 /// Sends data to a message queue.
685 /// \~english @param[in] hMessage
686 /// HANDLE - handle to the send message queue, McOpenSender
687 /// \~english @param[in] source
688 /// PCSTR - app (You) the sender
689 /// \~english @param[in] cmd
690 /// UI_32 - command id aka the message that's being sent
691 /// \~english @param[in] length
692 /// UI_32 - length of the data buffer provided
693 /// \~english @param[in] data
694 /// PCVOID - pointer to the data to be sent
695 /// \~english @param[in] sessionid
696 /// UI_32 - session id
697 /// \~english @retval EFrameworkunifiedStatus indicates if the message was sent successfully
698 /// \~english @retval eFrameworkunifiedStatusOK - Success
699 /// \~english @retval eFrameworkunifiedStatusNullPointer - NULL pointer specified
700 /// \~english @retval eFrameworkunifiedStatusInvldHandle - Invalid handle
701 /// \~english @retval eFrameworkunifiedStatusInvldHndlType - Invalid type of handle
702 /// \~english @retval eFrameworkunifiedStatusInvldQName - Illegal Message Queue name
703 /// \~english @retval eFrameworkunifiedStatusMsgQFull - Message queue is full
704 /// \~english @retval eFrameworkunifiedStatusErrNoEBADF - Invalid File-Descriptor
705 /// \~english @retval eFrameworkunifiedStatusErrNoEINTR - An interrupt is generated by the system call (signal)
706 /// \~english @retval eFrameworkunifiedStatusInvldBufSize - Invalid buffer-size
707 /// \~english @retval eFrameworkunifiedStatusFail - Some sort of error occurred
708 /// \~english @retval eFrameworkunifiedStatusErrOther - other errors(Failed to open/allocate shared memory)
709 /// \~english @retval eFrameworkunifiedStatusInvldParam - Invalid parameter
710 /// \~english @par Preconditons
711 /// - Message queue(McOpenSender) for sending message is created.
712 /// \~english @par Change of internal status
714 /// \~english @par Conditions of processing failure
715 /// - Message queue HANDLE in HANDLE specified in the argument (hService) is NULL. [eFrameworkunifiedStatusInvldHandle]
716 /// - HANDLE specified in the argument message queue HANDLE in (hService) is not appropriate (which is invalid).
717 /// [eFrameworkunifiedStatusInvldHandle]
718 /// - Application name of sender specified in the argument (source) is NULL. [eFrameworkunifiedStatusInvldQName]
719 /// - Application name of sender specified in the argument (source) exceeds 20byte. [eFrameworkunifiedStatusInvldQName]
720 /// - Sender data does not match sender data size(size is larger then 0, and data is NULL). [eFrameworkunifiedStatusInvldBuf]
721 /// - Message queue type of handle specified by argument(hMessage) is not sending type. [eFrameworkunifiedStatusInvldHndlType]
722 /// - Message queue is full. [eFrameworkunifiedStatusMsgQFull]
723 /// - File descriptor for sending message is invalid. [eFrameworkunifiedStatusErrNoEBADF]
724 /// - An interrupt is generated by the system call (signal) when sending message. [eFrameworkunifiedStatusErrNoEINTR]
725 /// - Size of buffer for sending message is invalid. [eFrameworkunifiedStatusInvldBufSize]
726 /// - Some errors occur, when sending message. [eFrameworkunifiedStatusFail]
727 /// - Failed to access(shm_open/ftruncate/mmap) the shared memory for sending message data. [eFrameworkunifiedStatusErrOther]
728 /// - Sending data size specified in the argument (length) is out of range. [eFrameworkunifiedStatusInvldParam]
729 /// \~english @par Detail
730 /// It is an asynchronous API. It provides function to send message by message queue. \n
731 /// Message queue name created by McOpenSender is the sender.
733 /// This API provides the inter-process communication function by the message queue for the application
734 /// which does not use the inter-process communication by NS Framework Dispatcher.
736 /// Command ID must be within the range PROTOCOL_FRAMEWORKUNIFIED_BASE_CMD(0x10) to PROTOCOL_FRAMEWORKUNIFIED_MAX_CMD(0xFFFFFFF0).
738 /// Please note the following points when using this API for application.
739 /// - McSend should be used if no sessionid is specified.
740 /// - To communicate with an application that uses NS Framework Dispatcher, use FrameworkunifiedSendMsg, etc.
741 /// - The maximum transmission data size (length) described above is a theoretical value,
742 /// and the maximum actually usable data size depends on the environment requirements.\n
743 /// - The maximum value is the upper limit of the type (UNIT_MAX) minus the following size.\n
744 /// Message header section\n
745 /// - Operation cannot be guaranteed when the size of the allocated area indicated by the address
746 /// of the pointer (data) to the data buffer does not match the size specified by the size of the data buffer (length).
747 /// \~english @par Classification
749 /// \~english @par Type
751 /// \~english @see McOpenSender, McSend, McReceiveWithSession, FrameworkunifiedSendMsg
752 //////////////////////////////////////////////////////////////////////////////////////////////
753 EFrameworkunifiedStatus McSendWithSession(HANDLE hMessage, PCSTR source, UI_32 cmd, UI_32 length, PCVOID data, UI_32 sessionid);
755 //////////////////////////////////////////////////////////////////////////////////////////////
756 /// \ingroup McSendWithPriority
757 /// \~english @par Brief
758 /// Sends data to a message queue, inserts based on priority given.
759 /// \~english @param[in] hMessage
760 /// HANDLE - handle to the send message queue, McOpenSender
761 /// \~english @param[in] source
762 /// PCSTR - app (You) the sender
763 /// \~english @param[in] cmd
764 /// UI_32 - command id aka the message that's being sent
765 /// \~english @param[in] length
766 /// UI_32 - length of the data buffer provided
767 /// \~english @param[in] data
768 /// PCVOID - pointer to the data to be sent
769 /// \~english @param[in] sessionid
770 /// UI_32 - session id
771 /// \~english @retval EFrameworkunifiedStatus indicates if the message was sent successfully
772 /// \~english @retval eFrameworkunifiedStatusOK(success)
773 /// \~english @retval eFrameworkunifiedStatusFail(anything else)
774 /// \~english @par Preconditons
776 /// \~english @par Change of internal status
777 /// - The internal state is not changed.
778 /// \~english @par Conditions of processing failure
779 /// - Function pointer specified by the argument is NULL.
780 /// - It is an incorrect value(hMessage) or hMessage is NULL.
781 /// - It is an incorrect value(source) or hMessage is NULL.
782 /// - It is an incorrect value(data) or hMessage is NULL.
783 /// - It is an incorrect value(priority).
784 /// - It is an incorrect value(sessionid).
785 /// \~english @par Detail
786 /// Invoke callback function with arguments to send data to message queue based on priority given.\n
787 /// If callback function is null and expectedCalls is '0', using default function 'McSendWithPriority' to send
788 /// data to message queue based on priority given.
790 /// This API provides the inter-process communication function by the message queue for the application
791 /// which does not use the inter-process communication by NS Framework Dispatcher.
793 /// Command ID must be within the range PROTOCOL_FRAMEWORKUNIFIED_BASE_CMD(0x10) to PROTOCOL_FRAMEWORKUNIFIED_MAX_CMD(0xFFFFFFF0).
795 /// Please note the following points when using this API for application.
796 /// - McSend should be used if no sessionid is specified.
797 /// - To communicate with an application that uses NS Framework Dispatcher, use FrameworkunifiedSendMsg, etc.
798 /// - The maximum transmission data size (length) described above is a theoretical value,
799 /// and the maximum actually usable data size depends on the environment requirements.\n
800 /// The maximum value is the upper limit of the type (UNIT_MAX) minus the following size.\n
801 /// Message header section\n
802 /// - Operation cannot be guaranteed when the size of the allocated area indicated by the address
803 /// of the pointer (data) to the data buffer does not match the size specified by the size of the data buffer (length).
805 /// \~english @par Classification
807 /// \~english @par Type
810 // McOpenSender, McSend, McSendWithSession, FrameworkunifiedSendMsg
811 //////////////////////////////////////////////////////////////////////////////////////////////
812 EFrameworkunifiedStatus McSendWithPriority(HANDLE hMessage, PCSTR source, UI_32 cmd, UI_32 length, PCVOID data,
813 EFrameworkunifiedMessagePriorties priority, UI_32 sessionid);
815 // EFrameworkunifiedStatus McSendWithPriorityWithSession(HANDLE hMessage, PCSTR source, UI_32 cmd, UI_32 length, PCVOID data,
816 // EFrameworkunifiedMessagePriorties priority, UI_32 sessionid);
818 ////////////////////////////////////////////////////////////////////////////////////////////
819 /// \ingroup McInvokeSync
820 /// \~english @par Brief
821 /// Synchronous Invoke. Send data to message queue, and Receive data from message queue.
822 /// \~english @param[in] hMessage
823 /// HANDLE - handle to the send message queue, McOpenSender
824 /// \~english @param[in] source
825 /// PCSTR - app (You) the sender
826 /// \~english @param[in] cmd
827 /// UI_32 - command id aka the message that's being sent
828 /// \~english @param[in] msgLength
829 /// UI_32 - length of the data buffer provided
830 /// \~english @param[in] msgData
831 /// PCVOID - pointer to the data to be sent
832 /// \~english @param[in] sessionid
833 /// UI_32 - session ID
834 /// \~english @param[in] hRcvMessage
835 /// HANDLE - handle to the receive message queue, McOpenSyncReceiver
836 /// \~english @param[in] responseLength
837 /// UI_32 - length of the responnce receive buffer provided
838 /// \~english @param[out] responseData
839 /// PVOID - pointer to the data to be receive
840 /// \~english @param[out] receivedLength
841 /// UI_32* - length of the data to be receive
842 /// \~english @retval EFrameworkunifiedStatus indicates invoke response or message sent error or response receive error
843 /// \~english @retval eFrameworkunifiedStatusOK - success
844 /// \~english @retval eFrameworkunifiedStatusInvldParam - Invalid parameter
845 /// \~english @retval eFrameworkunifiedStatusInvldHandle - Invalid handle
846 /// \~english @retval eFrameworkunifiedStatusInvldHndlType - Invalid handle type
847 /// \~english @retval eFrameworkunifiedStatusInvldQName - Invalid message queue name
848 /// \~english @retval eFrameworkunifiedStatusMsgQFull - Message queue is full
849 /// \~english @retval eFrameworkunifiedStatusErrNoEBADF - Invalid file descriptor
850 /// \~english @retval eFrameworkunifiedStatusErrNoEINTR - An interrupt is generated by the system call (signal)
851 /// \~english @retval eFrameworkunifiedStatusInvldBufSize - Invalid buffer size
852 /// \~english @retval eFrameworkunifiedStatusInvldBuf - Invalid buffer
853 /// \~english @retval eFrameworkunifiedStatusBadConnection - Can't connect with Socket
854 /// \~english @retval eFrameworkunifiedStatusFail - Some sort of error occurred
855 /// \~english @retval eFrameworkunifiedStatusErrOther - other errors(Failed to open/allocate shared memory)
856 /// \~english @par Preconditons
857 /// - Message queue specified by argument hMessage and hRcvMessage is useful.
858 /// \~english @par Change of internal status
860 /// \~english @par Conditions of processing failure
861 /// - Message queue handle specified in the argument (hMessage) for sending message is NULL.
862 /// [eFrameworkunifiedStatusInvldHandle]
863 /// - Message queue handle specified in the argument (hMessage) for sending message is not appropriate (which is
864 /// invalid). [eFrameworkunifiedStatusInvldHandle]
865 /// - Message queue handle specified in the argument (hRcvMessage) for receiving message is NULL.
866 /// [eFrameworkunifiedStatusInvldHandle]
867 /// - Message queue handle specified in the argument (hRcvMessage) for receiving message is not appropriate (which
868 /// is invalid). [eFrameworkunifiedStatusInvldHandle]
869 /// - Size of buffer(responseLength) which is used to storage received message is not 0,
870 /// but the pointer to this buffer(responseData) is NULL. [eFrameworkunifiedStatusInvldHandle]
871 /// - Failed to create buffer to storage the response message. [eFrameworkunifiedStatusFail]
872 /// - Failed to generete random number of the sequence ID for sending message. [eFrameworkunifiedStatusFail]
873 /// - Data size of sending message is not 0, but the message data(msgData) is NULL. [eFrameworkunifiedStatusInvldBuf]
874 /// - Application name of sender specified in the argument (source) is NULL. [eFrameworkunifiedStatusInvldQName]
875 /// - Application name of sender specified in the argument (source) exceeds 20byte. [eFrameworkunifiedStatusInvldQName]
876 /// - Name of message queue handle specified in the argument (hMessage) for sending message is NULL.
877 /// [eFrameworkunifiedStatusInvldHandle]
878 /// - Name of message queue handle specified in the argument (hMessage) for sending message exceeds 20byte.
879 /// [eFrameworkunifiedStatusInvldHandle]
880 /// - Size of sending message specified in the argument is not 0,
881 /// but the pointer to sending message is NULL. [eFrameworkunifiedStatusInvldBuf]
882 /// - Message queue type of handle specified by argument(hMessage) is not sending type. [eFrameworkunifiedStatusInvldHndlType]
883 /// - Message queue for sending message is full. [eFrameworkunifiedStatusMsgQFull]
884 /// - File descriptor of message queue for sending message is invalid. [eFrameworkunifiedStatusErrNoEBADF]
885 /// - An interrupt is generated by the system call (signal) when sending message. [eFrameworkunifiedStatusErrNoEINTR]
886 /// - Size of buffer for sending message is invalid. [eFrameworkunifiedStatusInvldBufSize]
887 /// - Some errors occur, when sending message. [eFrameworkunifiedStatusFail]
888 /// - Failed to access the shared memory for sending message data. [eFrameworkunifiedStatusErrOther]
889 /// - Failed to connect with the socket(socket/bind/connect) for checking the connection with application of
890 /// sender. [eFrameworkunifiedStatusFail]
891 /// - Failed to wait(epoll_create/epoll_ctl/epoll_wait) for receiving response message. [eFrameworkunifiedStatusFail]
892 /// - Failed to reconnect with the socket(socket/bind/connect) for checking the connection with application of
893 /// sender. [eFrameworkunifiedStatusBadConnection]
894 /// - Application name of sender in response message exceeds 20byte.[eFrameworkunifiedStatusInvldBuf]
895 /// - Message queue type of handle specified by argument(hMessage) is not receiving type.
896 /// [eFrameworkunifiedStatusInvldHndlType]
897 /// - File descriptor of message queue for receiving message is invalid. [eFrameworkunifiedStatusErrNoEBADF]
898 /// - An interrupt is generated by the system call (signal) when receiving message. [eFrameworkunifiedStatusErrNoEINTR]
899 /// - Size of buffer for receiving message is invalid. [eFrameworkunifiedStatusInvldBufSize]
900 /// - Received message is storaged in shared memory, but data size of shared memory is 0. [eFrameworkunifiedStatusErrOther]
901 /// - Failed to create buffer(calloc) to storage date getted from shared memory. [eFrameworkunifiedStatusFail]
902 /// - Failed to access(shm_open/fstat/mmap) the shared memory for receiving message data. [eFrameworkunifiedStatusErrOther]
903 /// - Data size of received message specified by argument(receivedLength) is NULL. [eFrameworkunifiedStatusInvldParam]
904 /// - Sending data size specified in the argument (msgLength) is out of range. [eFrameworkunifiedStatusInvldParam]
905 /// \~english @par Detail
906 /// It provides synchronous communication for message queue between sender and receiver specified in the
908 /// As it is a synchronous function, after sending a message, the sender will wait until getting response form
910 /// After receiving the response, set responseData with the received data and return.
912 /// This API provides the inter-process communication function by the message queue for the application
913 /// which does not use the inter-process communication by NS Framework Dispatcher.
915 /// When data larger than the receive message storage buffer size (resposeLength) is received,
916 /// the write size to the receive message storage buffer (responseData) does not exceed the specified size,
917 /// but the receive size is set in the receive message data length (recievedLength) as is.
919 /// The caller must guarantee the allocation of the receive message storage buffer (resonseData) area
920 /// and the consistency of the receive message stoage buffer sizes (resposeLength).
922 /// Please note the following points when using this API for application.
923 /// - This API stores up to the storage buffer length (responseLength) and returs eFrameworkunifiedStatusOK even
924 /// if the received reply message is larger than the storage buffer (responseData) size.\n
925 /// Therefore, the application shoud compare the received message length (recievedLenght) and the storage buffer length (responseLength) even
926 /// if this API returns eFrameworkunifiedStatusOK, and detect the above.
927 /// - Specify 0 for the sessionid of argument.
928 /// If a value other than 0 is specified, no error occurs and the value is used as is.
929 /// - To communicate with an application that uses NS Framework Dispatcher, use FrameworkunifiedInvokeSync, etc.
930 /// - The maximum data lenght (msgLength) of sent messages is a theoretical value,
931 /// and the maximum value that can be actually used is environment-depedent.\n
932 /// The maximum value is the upper limit of the type (UNIT_MAX) minus the following size.\n
933 /// Message header section, System information department in messages\n
934 /// - Operation cannot be guaranteed when the size of the allocated area indicated by the address
935 /// of the pointer (msgData) to the data buffer does not match the size specified by the size of the data buffer (msgLength).
936 /// \~english @par Classification
938 /// \~english @par Type
940 /// \~english @see McOpenSender, McOpenSyncReceiver, FrameworkunifiedInvokeSync
941 ////////////////////////////////////////////////////////////////////////////////////////////
942 EFrameworkunifiedStatus McInvokeSync(HANDLE hMessage, PCSTR source, UI_32 cmd, UI_32 msgLength, PCVOID msgData, UI_32 sessionid,
943 HANDLE hRcvMessage, UI_32 responseLength, PVOID responseData, UI_32 *receivedLength);
945 //////////////////////////////////////////////////////////////////////////////////////////////
946 /// \ingroup McSendSyncResponse
947 /// \~english @par Brief
948 /// Sends response to a message queue.
949 /// \~english @param[in] hMessage
950 /// HANDLE - handle to the send message queue, McOpenSyncSender
951 /// \~english @param[in] source
952 /// PCSTR - app (You) the sender
953 /// \~english @param[in] cmd
954 /// UI_32 - command id aka the message that's being sent
955 /// \~english @param[in] seq_id
956 /// UI_32 - response sequence ID
957 /// \~english @param[in] ret_val
958 /// EFrameworkunifiedStatus - response status
959 /// \~english @param[in] length
960 /// UI_32 - length of the data buffer provided
961 /// \~english @param[in] data
962 /// PCVOID - pointer to the data to be sent
963 /// \~english @retval eFrameworkunifiedStatusOK success
964 /// \~english @retval eFrameworkunifiedStatusInvldHandle - If handle is NULL or invalid
965 /// \~english @retval eFrameworkunifiedStatusInvldHndlType -if handle type is invalid
966 /// \~english @retval eFrameworkunifiedStatusInvldQName - if MQ name is invalid
967 /// \~english @retval eFrameworkunifiedStatusMsgQFull - if MQ is full
968 /// \~english @retval eFrameworkunifiedStatusErrNoEBADF - if fd is invalid
969 /// \~english @retval eFrameworkunifiedStatusErrNoEINTR - if system call(signal) interupt occurs
970 /// \~english @retval eFrameworkunifiedStatusInvldBufSize -if buffer size is invalid
971 /// \~english @retval eFrameworkunifiedStatusInvldBuf -if buffer is invalid
972 /// \~english @retval eFrameworkunifiedStatusFail - any other error
973 /// \~english @retval eFrameworkunifiedStatusErrOther -other error(memory open/allocate fail)
974 /// \~english @par Preconditons
975 /// - The message queue specified by argument hMessage of this API must be allocated
976 /// in advance by McOpenSender and McOpenSyncSender.
977 /// \~english @par Change of internal status
979 /// \~english @par Conditions of processing failure
980 /// - sending MQ handle(designated by parameter)is NULL[eFrameworkunifiedStatusInvldHandle]
981 /// - sending MQ handle(designated by parameter)is invalid[eFrameworkunifiedStatusInvldHandle]
982 /// - the type of sending MQ handle(designated by parameter)is not sending type[eFrameworkunifiedStatusInvldHndlType]
983 /// - application name(source,designated by parameter)is NULL[eFrameworkunifiedStatusInvldQName]
984 /// - the length of application name(designated by parameter)is over 20byte[eFrameworkunifiedStatusInvldQName]
985 /// - sending data not in accordance with the size of sending data(eg:size is not 0 but data is NULL)
986 /// [eFrameworkunifiedStatusInvldBuf]
987 /// - sending data MQ is full [eFrameworkunifiedStatusMsgQFull]
988 /// - fd of sending data MQ is invalid [eFrameworkunifiedStatusErrNoEBADF]
989 /// - system call(signal) interupt occurs during MQ receiveing process[eFrameworkunifiedStatusErrNoEINTR]
990 /// - the size of receiveing MQ buffer is invalid[eFrameworkunifiedStatusInvldBufSize]
991 /// - error occurs during MQ receiveing process [eFrameworkunifiedStatusFail]
992 /// - failed to access shared memmory for sending message[eFrameworkunifiedStatusErrOther]
993 /// - failed to allocate buffer for data retriving from shared memmory[eFrameworkunifiedStatusFail]
994 /// \~english @par Detail
995 /// set the response data to buffer and call this API
996 /// when need to response to synchronous message get from synchronous communication(McInvokeSync)
998 /// This API applies communication function(using message queue)between processes to the application which do not
1000 /// Dispatcher of NS Framework
1002 /// cautions when using this API
1003 /// - Use FrameworkunifiedSetSyncResponseData if communacate with application which use the Dispatcher of NS Framework\n
1004 /// - the limit of size for sending data is according to system
1005 /// but the total size of SSystemMsgHeader and ResponseHeader shared memmory header is 48byte
1006 /// size limit should be(UINT_MAX-48byte)
1007 /// - operation is not guaranteed if the size which shown in data buffer pointer(data) is not in
1008 /// accordance with the length set in data buffer
1009 /// \~english @par Classification
1011 /// \~english @par Type
1013 /// \~english @see McOpenSender, McOpenSyncReceiver, McInvokeSync, FrameworkunifiedSetSyncResponseData
1014 //////////////////////////////////////////////////////////////////////////////////////////////
1015 EFrameworkunifiedStatus McSendSyncResponse(HANDLE hMessage, PCSTR source, UI_32 cmd, UI_32 seq_id, EFrameworkunifiedStatus ret_val, UI_32 length,
1018 ////////////////////////////////////////////////////////////////////////////////////////////
1019 /// \ingroup McCreateInvokerName
1020 /// \~english @par Brief
1021 /// Create synchronous invoke response MQ name.
1022 /// \~english @param[in] source
1023 /// PCSTR - source service name
1024 /// \~english @param[in] sessionid
1025 /// UI_32 - session id
1026 /// \~english @param[in] invokerName
1027 /// PSTR - create invoker name buffer
1028 /// \~english @param[in] size
1029 /// UI_32 - InvokerName buffer size
1030 /// \~english @retval EFrameworkunifiedStatus indicates if the close was successfully
1031 /// \~english @retval eFrameworkunifiedStatusOK
1032 /// \~english @retval eFrameworkunifiedStatusInvldParam -if parameter is invalid
1033 /// \~english @par Preconditons
1035 /// \~english @par Change of internal status
1037 /// \~english @par Conditions of processing failure
1038 /// - sender application name(source,designated by parameter) is NULL[eFrameworkunifiedStatusInvldParam]
1039 /// - synchronous communication MQ name(invokerName,designated by parameter) is NULL[eFrameworkunifiedStatusInvldParam]
1040 /// - the size of synchronous communication MQ name buffer(designated by parameter)is NULL[eFrameworkunifiedStatusInvldParam]
1041 /// \~english @par Detail
1042 /// This API will add specific letters to the end of sender application name and return it as synchronous
1043 /// communication MQ name
1044 /// This name will be used when application create the MQ through McOpenSyncReceiver
1046 /// cautions when using this API:
1047 /// - the synchronous communication MQ name(invokerName) buffer size should be larger than the length of source
1049 /// name(at least 4byte larger)
1050 /// - source application name(designated by parameter) should be less than 15byte(according to NS framework
1051 /// spec,error occurs
1052 /// if message name length is over 20byte
1053 /// \~english @par Classification
1055 /// \~english @par Type
1057 /// \~english @see McOpenSyncReceiver
1058 ////////////////////////////////////////////////////////////////////////////////////////////
1059 EFrameworkunifiedStatus McCreateInvokerName(PCSTR source, UI_32 sessionid, PSTR invokerName, UI_32 size);
1061 ////////////////////////////////////////////////////////////////////////////////////////////
1062 /// \ingroup McClose
1063 /// \~english @par Brief
1064 /// Close a connection to a Receiver message queue.
1065 /// \~english @param[in] hMessage
1066 /// HANDLE - handle that will be closed
1067 /// \~english @retval EFrameworkunifiedStatus indicates if the close was successfully
1068 /// \~english @retval eFrameworkunifiedStatusOK success
1069 /// \~english @retval eFrameworkunifiedStatusInvldHandle - If hMessage is NULL or invalid
1070 /// \~english @retval eFrameworkunifiedStatusInvldHndlType - if hMessage is invalid
1071 /// \~english @par Preconditons
1072 /// message queue(McOpenSender, McOpenReceiver) is created in advance
1073 /// \~english @par Change of internal status
1075 /// \~english @par Conditions of processing failure
1076 /// - handle(hMessage,designated by parameter) is NULL[eFrameworkunifiedStatusInvldHandle]
1077 /// - handle(hMessage,designated by parameter) is invalid[eFrameworkunifiedStatusInvldHandle]
1078 /// - the type of handle(designated by parameter) is neither sending or receiveing[eFrameworkunifiedStatusInvldHndlType]
1079 /// - fail to close the message queue(mq_close)[eFrameworkunifiedStatusInvldHandle]
1080 /// \~english @par Detail
1081 /// close the message sending or receiveing message queue which is designated by parameter\n
1082 /// Application can call this API to close the message queue which is created by McOpenSender
1083 /// \~english @par Classification
1085 /// \~english @par Type
1087 /// \~english @see McOpenSender, McOpenReceiver, McOpenSyncReceiver
1088 ////////////////////////////////////////////////////////////////////////////////////////////
1089 EFrameworkunifiedStatus McClose(HANDLE hMessage);
1091 //////////////////////////////////////////////////////////////////////////////////////////////
1092 /// \ingroup McGetDataUSID
1093 /// \~english @par Brief
1094 /// Get the USID is the Unique Shared Memory ID.e. from the message that was received.
1095 /// \~english @param[in] pData
1096 /// void* - pointer to the data was received from the McReceive Call
1097 /// \~english @retval TMemID Type of memory buffer identifiers(unsigned int).
1098 /// \~english @retval NoneZero(Success)
1099 /// \~english @retval Zero(Failed)
1100 /// \~english @par Preconditons
1102 /// \~english @par Change of internal status
1103 /// - The internal state is not changed.
1104 /// \~english @par Conditions of processing failure
1105 /// - Function pointer specified by the argument is NULL.
1106 /// - It is an incorrect value(pData) or pData is NULL.
1107 /// \~english @par Detail
1108 /// Invoke callback function with arguments to get the USID from the message that was received.\n
1109 /// If callback function is null and expectedCalls is '0', using default function 'McGetDataUSID' to get the USID
1110 /// from the message that was received.\n
1111 /// \~english @par Classification
1113 /// \~english @par Type
1116 // FrameworkunifiedGetDataUSID, FrameworkunifiedForwardMessage
1117 //////////////////////////////////////////////////////////////////////////////////////////////
1118 TMemID McGetDataUSID(PVOID pData);
1120 //////////////////////////////////////////////////////////////////////////////////////////////
1121 /// \ingroup McGetMsgSrc
1122 /// \~english @par Brief
1123 /// Gets the constant pointer to source message queue.
1124 /// \~english @param[in] data
1125 /// PVOID - pointer to the data to be received
1126 /// \~english @retval PCSTR message queue's address
1127 /// CONST char* - constant pointer to source message queue
1128 /// \~english @retval NotNull(Success)
1129 /// \~english @retval Null(Failed)
1130 /// \~english @par Preconditons
1132 /// \~english @par Change of internal status
1133 /// - The internal state is not changed.
1134 /// \~english @par Conditions of processing failure
1135 /// - Function pointer specified by the argument is NULL.
1136 /// - It is an incorrect value(data) or data is NULL.
1137 /// \~english @par Detail
1138 /// Invoke callback function with arguments to get the constant pointer to source message queue.\n
1139 /// If callback function is null and expectedCalls is '0', using default function 'McGetMsgSrc' to the constant
1140 /// pointer to source message queue.\n
1141 /// \~english @par Classification
1143 /// \~english @par Type
1146 // frameworkunifiedSendSyncResponse, frameworkunifiedProcessSyncResponse
1147 //////////////////////////////////////////////////////////////////////////////////////////////
1148 PCSTR McGetMsgSrc(PVOID data);
1151 //////////////////////////////////////////////////////////////////////////////////////////////
1152 /// \ingroup McForward
1153 /// \~english @par Brief
1154 /// Forward a Message to indicate that there is a Shared Memory
1155 /// \~english @param[in] hMessage
1156 /// HANDLE - handle to the send message queue, McOpenSender
1157 /// \~english @param[in] source
1158 /// PCSTR - the sender of this forwarding message.
1159 /// \~english @param[in] iCmd
1160 /// UI_32 - Command Id message to forward
1161 /// \~english @param[in] USID
1162 /// UI_32 - Unique Shared memory Id
1163 /// \~english @retval EFrameworkunifiedStatus indicates if the close was successfully
1164 /// CONST char* - constant pointer to source message queue
1165 /// \~english @retval Success(eFrameworkunifiedStatusOK)
1166 /// \~english @retval Failed(anything else)
1167 /// \~english @par Preconditons
1169 /// \~english @par Change of internal status
1170 /// - The internal state is not changed.
1171 /// \~english @par Conditions of processing failure
1172 /// - Function pointer specified by the argument is NULL.
1173 /// - It is an incorrect value(hMessage) or hMessage is NULL.
1174 /// - It is an incorrect value(source) or source is NULL.
1175 /// - It is an incorrect value(iCmd).
1176 /// - It is an incorrect value(USID).
1177 /// \~english @par Detail
1178 /// Invoke callback function with arguments to forward a Message.\n
1179 /// If callback function is null and expectedCalls is '0', using default function 'McForward' to forward a
1181 /// \~english @par Classification
1183 /// \~english @par Type
1186 // FrameworkunifiedForwardMessage
1187 //////////////////////////////////////////////////////////////////////////////////////////////
1188 EFrameworkunifiedStatus McForward(HANDLE hMessage, PCSTR source, UI_32 iCmd, TMemID USID);
1191 ////////////////////////////////////////////////////////////////////////////////////////////
1192 /// \ingroup McFlushReceiver
1193 /// \~english @par Brief
1194 /// Flush's all data on HANDLE's Receiver message queue.
1195 /// \~english @param[in] hMessage
1196 /// HANDLE - handle to the recvMessage queue that will be flushed
1197 /// \~english @retval void
1198 /// \~english @par Preconditons
1199 /// message queue(McOpenReceiver)is created in advance
1200 /// \~english @par Change of internal status
1202 /// \~english @par Conditions of processing failure
1203 /// - handle(hMessage,designated by parameter) is NULL
1204 /// - handle(hMessage,designated by parameter) is invalid [-1]
1205 /// - the type of handle(designated by parameter) is neither sending or receiveing[-1]
1206 /// \~english @par Detail
1207 /// message will not be flushed if process failed
1208 /// \~english @par Classification
1210 /// \~english @par Type
1212 /// \~english @see McOpenSender, McOpenReceiver, McOpenSyncReceiver
1213 ////////////////////////////////////////////////////////////////////////////////////////////
1214 void McFlushReceiver(HANDLE hMessage);
1216 ////////////////////////////////////////////////////////////////////////////////////////////
1217 /// \ingroup McGetQueueName
1218 /// \~english @par Brief
1219 /// Gets the name of the message queue.
1220 /// \~english @param[in] hMessage
1221 /// HANDLE - handle of the message queue,
1222 /// (handle created with McOpenReceiver or McOpenSender)
1223 /// \~english @retval PCSTR name - name of the message queue if handle is valid else NULL
1224 /// \~english @par Preconditons
1225 /// Dispatcher for application should be created and initilized(FrameworkunifiedCreateDispatcherWithoutLoop)in advance
1226 /// \~english @par Change of internal status
1228 /// \~english @par Conditions of processing failure
1229 /// - handle(hMessage,designated by parameter) is NULL
1230 /// - handle(hMessage,designated by parameter) is invalid [-1]
1231 /// - the type of handle(designated by parameter) is neither sending or receiveing[-1]
1232 /// \~english @par Detail
1233 /// return the name of specific message queue
1234 /// this APL is used for application to supervize message queue
1236 /// This API applies communication function(using message queue)between processes to the application which do not
1238 /// Dispatcher of NS Framework
1239 /// \~english @par Classification
1241 /// \~english @par Type
1243 /// \~english @see McOpenReceiver, McOpenSender
1244 ////////////////////////////////////////////////////////////////////////////////////////////
1245 PCSTR McGetQueueName(HANDLE hMessage);
1247 ////////////////////////////////////////////////////////////////////////////////////////////
1248 /// \ingroup McGetQueueFD
1249 /// \~english @par Brief
1250 /// Gets the fd of the message queue.
1251 /// \~english @param[in] hMessage
1252 /// HANDLE - handle of the message queue.(handle created with McOpenReceiver or McOpenSender)
1253 /// \~english @retval int fd - fd of the message queue if handle is valid else -1
1254 /// \~english @par Preconditons
1255 /// - Dispatcher for application is created and initialized(FrameworkunifiedCreateDispatcherWithoutLoop) in advance
1256 /// \~english @par Change of internal status
1258 /// \~english @par Conditions of processing failure
1259 /// - handle(hMessage,designated by parameter) is NULL
1260 /// - handle(hMessage,designated by parameter) is invalid [-1]
1261 /// - the type of handle(designated by parameter) is neither sending or receiveing[-1]
1262 /// \~english @par Detail
1263 /// return the fd of specific message queue
1264 /// this APL is used for application to supervize message queue
1266 /// This API applies communication function(using message queue)between processes to the application which do not
1268 /// Dispatcher of NS Framework
1269 /// \~english @par Classification
1271 /// \~english @par Type
1273 /// \~english @see McOpenReceiver, McOpenSender
1274 ////////////////////////////////////////////////////////////////////////////////////////////
1275 int McGetQueueFD(HANDLE hMessage);
1277 //////////////////////////////////////////////////////////////////////////////////////////////
1278 /// \ingroup McTranslateError
1279 /// \~english @par Brief
1280 /// Translates global error variables into FW EFrameworkunifiedStatus
1281 /// \~english @param[in] error
1282 /// int - error variable
1283 /// \~english @retval EFrameworkunifiedStatus indicates frameworkunified error type
1285 /// EFrameworkunifiedStatus Enum
1287 /// typedef enum eFrameworkunifiedStatus {
1288 /// eFrameworkunifiedStatusEmptyMediaList = -10, ///< Empty media list
1289 /// eFrameworkunifiedStatusSessionLimitMaxedOut = -9, ///< Maximum session limit reached
1290 /// eFrameworkunifiedStatusDbRecNotFound = -8, ///< Database record not found
1291 /// eFrameworkunifiedStatusDbResultError = -7, ///< Database result error
1292 /// eFrameworkunifiedStatusDbExecuteFail = -6, ///< Database execute fail
1293 /// eFrameworkunifiedStatusSemCloseFail = -5, ///< Semaphore close failed
1294 /// eFrameworkunifiedStatusSemUnlockFail = -4, ///< Semaphore unlock failed
1295 /// eFrameworkunifiedStatusSemLockFail = -3, ///< Semaphore lock failed
1296 /// eFrameworkunifiedStatusFail = -2, ///< Failed
1297 /// eFrameworkunifiedStatusErrOther = -1, ///< Unknown error
1298 /// eFrameworkunifiedStatusOK = 0, ///< Success / Pass / OK
1299 /// eFrameworkunifiedStatusInvldBuf = 1, ///< Invalid buffer
1300 /// eFrameworkunifiedStatusInvldHandle = 2, ///< Invalid handle
1301 /// eFrameworkunifiedStatusInvldHndlType = 3, ///< Invalid handle type
1302 /// eFrameworkunifiedStatusInvldQName = 4, ///< Invalid messasge queue name
1303 /// eFrameworkunifiedStatusMsgQFull = 5, ///< Message queue full
1304 /// eFrameworkunifiedStatusInvldNotification = 6,///< The Notification event not present
1305 /// eFrameworkunifiedStatusInvldParam = 7, ///< Invalid parameter
1306 /// eFrameworkunifiedStatusInvldBufSize = 8, ///< Buf size too small
1307 /// eFrameworkunifiedStatusInvldID = 9, ///< Unrecognized ID
1308 /// eFrameworkunifiedStatusCannotRelease = 10, ///< Cannot release resource
1309 /// eFrameworkunifiedStatusBadConnection = 11, ///< Could not locate resource
1310 /// eFrameworkunifiedStatusExit = 12, ///< Normal application termination
1311 /// eFrameworkunifiedStatusNotImplemented = 13, ///< incomplete feature
1312 /// eFrameworkunifiedStatusThreadBusy = 14, ///< Joined thread is already being joined
1313 /// eFrameworkunifiedStatusThreadSelfJoin = 15, ///< Thread is joining itself
1314 /// eFrameworkunifiedStatusThreadInvalidVal = 16, ///< Invalid value passed
1315 /// eFrameworkunifiedStatusThreadNotExist = 17, ///< The thread does not exist
1316 /// eFrameworkunifiedStatusFault = 18, ///< A fault occurred while attempting to make call
1317 /// eFrameworkunifiedStatusServNotFound = 19, ///< Service not present in serv dir
1318 /// eFrameworkunifiedStatusServerInUse = 20, ///< Service already processing 1 client request
1319 /// eFrameworkunifiedStatusDbIndexing = 21, ///< Database Indexing in progress
1320 /// eFrameworkunifiedStatusNullPointer = 22,
1321 /// eFrameworkunifiedStatusMsgNotProcessed = 23,
1322 /// eFrameworkunifiedStatusFileLoadSuccess = 24, ///< File Load Success
1323 /// eFrameworkunifiedStatusFileLoadError = 25, ///< File Load Error
1324 /// eFrameworkunifiedStatusAccessError = 26, ///< Error when accessing resource
1325 /// eFrameworkunifiedStatusDuplicate = 27, ///< Duplicate entry
1326 /// eFrameworkunifiedStatusMsgQEmpty = 28, ///< Message queue empty
1327 /// eFrameworkunifiedStatusThreadAlreadyRunning = 29,
1328 /// eFrameworkunifiedStatusErrNoEBADF = 30, ///< Bad file descriptor
1329 /// eFrameworkunifiedStatusErrNoEAGAIN = 31, ///< Resource unavailable, try again
1330 /// eFrameworkunifiedStatusErrNoEINTR = 32, ///< Interrupted system call
1331 /// eFrameworkunifiedStatusSessionErr = 33, ///< Error in session handling
1332 /// eFrameworkunifiedStatusDBCorrupt = 34, ///< Database corrupt
1333 /// eFrameworkunifiedStatusDBFileNotFound = 35 ///< Database file not found
1334 /// } EFrameworkunifiedStatus, *PEFrameworkunifiedStatus;
1336 /// \~english @par Preconditons
1338 /// \~english @par Change of internal status
1339 /// - The internal state is not changed.
1340 /// \~english @par Conditions of processing failure
1341 /// - Function pointer specified by the argument is NULL.
1342 /// - It is an incorrect value(error).
1343 /// \~english @par Detail
1344 /// Invoke callback function with arguments to translates global error variables.\n
1345 /// If callback function is null and expectedCalls is '0', using default function 'McTranslateError' to translates
1346 /// global error variables.
1347 /// \~english @par Classification
1349 /// \~english @par Type
1353 //////////////////////////////////////////////////////////////////////////////////////////////
1354 EFrameworkunifiedStatus McTranslateError(int error);
1356 ////////////////////////////////////////////////////////////////////////////////////////////
1357 /// \ingroup McZcSetParam
1358 /// \~english @par Brief
1359 /// set variable parameter to messeg-sending header
1360 /// \~english @param[in] handle
1361 /// HANDLE - handle to the send message queue, McZcOpenSender
1362 /// \~english @param[in] cmd
1363 /// UI_32 -cmd for sending(ID to identify protocol of service)
1364 /// \~english @param[in] length
1365 /// UI_32 -size of buffer for message-sending
1366 /// \~english @retval EFrameworkunifiedStatus indicates if the message was set successfully
1367 /// \~english @retval eFrameworkunifiedStatusOK sucess
1368 /// \~english @retval eFrameworkunifiedStatusInvldHandle - If hMessage is NULL or invalid
1369 /// \~english @retval eFrameworkunifiedStatusInvldBuf - invalid buffer
1370 /// \~english @retval eFrameworkunifiedStatusInvldBufSize - invalid buffer size
1371 /// \~english @par Preconditons
1372 /// message queue is created by McZcOpenSender in advance
1373 /// \~english @par Change of internal status
1375 /// \~english @par Conditions of processing failure
1376 /// - handle(designated by parameter) is NULL[NULL]
1377 /// - handle(designated by parameter) is invalid [NULL]
1378 /// - the buffer for sending in handle(designated by parameter) is NULL[NULL]
1379 /// - the size of data for sending(designated by parameter)(except header) is larger than the size of
1380 /// sending-buffer[eFrameworkunifiedStatusInvldBufSize]
1381 /// \~english @par Detail
1382 /// set the variable sending cmd and sending data length in sending buffer of message-sending handle
1383 /// This API will only do the initialization of message header.detail setting of data for sending will be done\n
1384 /// Application can use McZcGetBuf to do data setting
1386 /// CMD ID should be in (PROTOCOL_FRAMEWORKUNIFIED_BASE_CMD(0x10) to PROTOCOL_FRAMEWORKUNIFIED_MAX_CMD(0xFFFFFFF0))
1388 /// cautions when using this API
1389 /// - detail data sending size should be in accordance with the data sending size which is set in this API
1390 /// \~english @par Classification
1392 /// \~english @par Type
1394 /// \~english @see McZcGetBuf, McZcSend
1395 ////////////////////////////////////////////////////////////////////////////////////////////
1396 EFrameworkunifiedStatus McZcSetParam(HANDLE handle, UI_32 cmd, UI_32 length);
1398 ////////////////////////////////////////////////////////////////////////////////////////////
1399 /// \ingroup McZcGetBuf
1400 /// \~english @par Brief
1401 /// get the fist address of buffer for sending
1402 /// \~english @param[in] handle
1403 /// HANDLE - handle to the send message queue, McZcOpenSender
1404 /// \~english @retval PVOID the first address of buffer for data-sending
1405 /// \~english @retval NULL NULL pointer(fail to get)
1406 /// \~english @par Preconditons
1407 /// message queue is created by McZcOpenSender in advance
1408 /// \~english @par Change of internal status
1410 /// \~english @par Conditions of processing failure
1411 /// - handle(designated by parameter) is NULL[NULL]
1412 /// - handle(designated by parameter) is invalid [NULL]
1413 /// - the buffer for sending in handle(designated by parameter) is NULL[NULL]
1414 /// \~english @par Detail
1415 /// get the first address of data(excpet the message-header)from sending-buffer in message-sending handle
1416 /// application will set the address got as sending message
1418 /// cautions When using the application
1419 /// - result will not be guaranteed if the handle set is different from message-sending queue handle
1420 /// \~english @par Classification
1422 /// \~english @par Type
1424 /// \~english @see McZcGetBuf
1425 ////////////////////////////////////////////////////////////////////////////////////////////
1426 PVOID McZcGetBuf(HANDLE handle);
1428 ////////////////////////////////////////////////////////////////////////////////////////////
1429 /// \ingroup McZcSend
1430 /// \~english @par Brief
1432 /// \~english @param[in] hMessage
1433 /// HANDLE - handle to the sendMessage, McZcOpenSender
1434 /// \~english @retval EFrameworkunifiedStatus indicates if the message was sent successfully
1435 /// \~english @retval eFrameworkunifiedStatusOK success
1436 /// \~english @retval eFrameworkunifiedStatusInvldHandle - If hMessage is NULL or invalid
1437 /// \~english @retval eFrameworkunifiedStatusInvldBuf - buffer is invalid
1438 /// \~english @retval eFrameworkunifiedStatusInvldHndlType -handle type is invalid
1439 /// \~english @retval eFrameworkunifiedStatusMsgQFull - message queue is full
1440 /// \~english @retval eFrameworkunifiedStatusErrNoEBADF - file descriptor invalid
1441 /// \~english @retval eFrameworkunifiedStatusErrNoEINTR -system call(signal) interupt
1442 /// \~english @retval eFrameworkunifiedStatusInvldBufSize -invalid buffer size
1443 /// \~english @par Preconditons
1444 /// message queuqe is created by McZcOpenSender
1445 /// \~english @par Change of internal status
1447 /// \~english @par Conditions of processing failure
1448 /// - handle(hMessage,designated by parameter)is NULL[eFrameworkunifiedStatusInvldHandle]
1449 /// - handle(hMessage,designated by parameter)is invalid[eFrameworkunifiedStatusInvldHandle]
1450 /// - the sending-buffer in handle(hMessage,designated by parameter)is NULL[eFrameworkunifiedStatusInvldBuf]
1451 /// - the type of message queue in handle(hMessage,designated by parameter)is not sending
1452 /// type[eFrameworkunifiedStatusInvldHndlType]
1453 /// - message-sending queue is full[eFrameworkunifiedStatusMsgQFull]
1454 /// - file descriptor of message-sending queue is invalid[eFrameworkunifiedStatusErrNoEBADF]
1455 /// - system call(singal) interupts during the message sending process[eFrameworkunifiedStatusErrNoEINTR]
1456 /// - the size of buffer for message-sending is invalid[eFrameworkunifiedStatusInvldBufSize]
1457 /// \~english @par Detail
1458 /// send message using specific message-sending handle.\n
1459 /// data for sending should be set to message-sending handle(hMessage)beforhead using McZcSetParam, McZcGetBuf
1460 /// \~english @par Classification
1462 /// \~english @par Type
1464 /// \~english @see McZcOpenSender, McZcSetParam, McZcGetBuf
1465 ////////////////////////////////////////////////////////////////////////////////////////////
1466 EFrameworkunifiedStatus McZcSend(HANDLE hMessage);
1468 ////////////////////////////////////////////////////////////////////////////////////////////
1469 /// \ingroup McZcOpenSender
1470 /// \~english @par Brief
1471 /// create message-sending queuqe
1472 /// \~english @param[in] source
1473 /// PCSTR - app (You) the sender
1474 /// \~english @retval Handle for sending messages to a queue (If INVALID_HANDLE is returned its an error)
1475 /// \~english @retval NULL NULL pointer(fail to get)
1476 /// \~english @par Preconditons
1478 /// \~english @par Change of internal status
1480 /// \~english @par Conditions of processing failure
1481 /// - message queue name(designated by parameter)is NULL[NULL]
1482 /// - the length of message queue name(designated by parameter)(source) is over 20byte[NULL]
1483 /// - fail to get memmory for restoring formated message queue name [NULL]
1484 /// - length of formated message queue name is over 15byte or 16byte(when initial letter is'/')[NULL]
1485 /// - fail to get message queue(mq_open)[NULL]
1486 /// - fail to get memmory for message queue info managment(malloc)[NULL]
1487 /// - fail to get memory for sending buffer[NULL]
1488 /// \~english @par Detail
1489 /// create message queuqe and return the handle
1490 /// \~english @par Classification
1492 /// \~english @par Type
1494 /// \~english @see McZcSetParam, McZcGetBuf, McZcSend, McZcClose
1495 ////////////////////////////////////////////////////////////////////////////////////////////
1496 HANDLE McZcOpenSender(PCSTR source);
1498 ////////////////////////////////////////////////////////////////////////////////////////////
1499 /// \ingroup McZcClose
1500 /// \~english @par Brief
1501 /// close the handle to message queue
1502 /// \~english @param[in] handle
1503 /// HANDLE - handle to the send message queue, handle got through McZcOpenSender
1504 /// \~english @retval EFrameworkunifiedStatus indicates if the message was close successfully
1505 /// \~english @retval eFrameworkunifiedStatusOK
1506 /// \~english @retval eFrameworkunifiedStatusInvldHandle - If hMessage is NULL or invalid
1507 /// \~english @retval eFrameworkunifiedStatusInvldHndlType If handle type is invalid
1508 /// \~english @par Preconditons
1509 /// - message queue is created by McZcOpenSender in advance
1510 /// \~english @par Change of internal status
1512 /// \~english @par Conditions of processing failure
1513 /// - message handle(designated by parameters) is NULL[eFrameworkunifiedStatusInvldHandle]
1514 /// - message handle(designated by parameters) is invalid [eFrameworkunifiedStatusInvldHandle]
1515 /// - message handle type(designated by parameters) is not match(neither send or receive)[eFrameworkunifiedStatusInvldHndlType]
1516 /// - fail to close message queue(mq_close)[eFrameworkunifiedStatusInvldHandle]
1517 /// \~english @par Detail
1518 /// Close message-sending or message-receiving handle(designated by parameters)\n
1519 /// application call this function to close message queue which is created by McZcOpenSender.
1520 /// \~english @par Classification
1522 /// \~english @par Type
1524 /// \~english @see McZcOpenSender
1525 ////////////////////////////////////////////////////////////////////////////////////////////
1526 EFrameworkunifiedStatus McZcClose(HANDLE handle);
1531 #endif /* __NATIVESERVICES_MESSAGE_CENTER_IF_H__ */ // NOLINT (build/header_guard)