video_in_hal/nsframework/framework_unified/client/include/native_service/ns_message_center_if.h

   1 /*
   2  * @copyright Copyright (c) 2016-2020 TOYOTA MOTOR CORPORATION.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 /**
  18  * @file
  19  * @brief \~english APIs to Open/Close and Send/Receive on message queues and shared memory.
  20  *
  21  */
  22 /** @addtogroup BaseSystem
  23  *  @{
  24  */
  25 /** @addtogroup native_service
  26  *  @ingroup BaseSystem
  27  *  @{
  28  */
  29 /** @addtogroup framework_unified
  30  *  @ingroup native_service
  31  *  @{
  32  */
  33 /** @addtogroup native
  34  *  @ingroup framework_unified
  35  *  @{
  36  */
  37 #ifndef __NATIVESERVICES_MESSAGE_CENTER_IF_H__  // NOLINT  (build/header_guard)
  38 #define __NATIVESERVICES_MESSAGE_CENTER_IF_H__
  39
  40 #include <native_service/frameworkunified_types.h>
  41 #include <native_service/ns_shared_mem_if.h>
  42
  43
  44 #ifdef __cplusplus
  45 extern "C" {
  46 #endif
  47
  48
  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
  57 ///        - none
  58 /// \~english @par Change of internal status
  59 ///        - none
  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
  64 ///       "/"]. [NULL]
  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
  73 ///          Public
  74 /// \~english @par Type
  75 ///          Sync only
  76 /// \~english @see McOpenSender, McReceive, McClose
  77 ////////////////////////////////////////////////////////////////////////////////////////////
  78 HANDLE McOpenReceiver(PCSTR name);
  79
  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
  89 ///        - none
  90 /// \~english @par Change of internal status
  91 ///        - none
  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
  96 ///       "/"]. [NULL]
  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
 105 ///          Public
 106 /// \~english @par Type
 107 ///          Sync only
 108 /// \~english @see McOpenSender, McReceive, McClose, McOpenSenderNotBlocked
 109 ////////////////////////////////////////////////////////////////////////////////////////////
 110 HANDLE McOpenReceiverNotBlocked(PCSTR name);
 111
 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
 120 ///        - none
 121 /// \~english @par Change of internal status
 122 ///        - none
 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.
 127 ///       [NULL]
 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.
 135 /// \~english @par
 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.
 138 /// \~english @par
 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
 147 ///          Public
 148 /// \~english @par Type
 149 ///          Sync only
 150 /// \~english @see McCreateInvokerName, McInvokeSync, McClose
 151 ////////////////////////////////////////////////////////////////////////////////////////////
 152 HANDLE McOpenSyncReceiver(PCSTR name);
 153
 154
 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
 163 ///        - none
 164 /// \~english @par Change of internal status
 165 ///        - none
 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
 170 ///       "/"]. [NULL]
 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.
 178 /// \~english @par
 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
 182 ///          Public
 183 /// \~english @par Type
 184 ///          Sync only
 185 /// \~english @see McOpenReceiver, McSend, McClose
 186 ////////////////////////////////////////////////////////////////////////////////////////////
 187 HANDLE McOpenSender(PCSTR name);
 188
 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.
 192 ///
 193 /// \param [in] name
 194 ///         PCSTR - name of the message queue you want to send messages too
 195 ///
 196 /// \return HANDLE
 197 ///         handle - for sending messages to a queue (If INVALID_HANDLE is returned its an error)
 198 ////////////////////////////////////////////////////////////////////////////////////////////
 199 HANDLE McOpenSenderNotBlocked(PCSTR name);
 200
 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
 209 ///        - none
 210 /// \~english @par Change of internal status
 211 ///        - none
 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.
 216 ///       [NULL]
 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.
 225 /// \~english @par
 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
 229 ///          Public
 230 /// \~english @par Type
 231 ///          Sync only
 232 /// \~english @see McOpenReceiver, McSend, McClose
 233 ////////////////////////////////////////////////////////////////////////////////////////////
 234 HANDLE McOpenSyncSender(PCSTR name);
 235
 236 /////////////////////////////////////////
 237 #include <pthread.h>
 238 HANDLE McOpenSenderChild(PCSTR name, pthread_t childid);
 239 /////////////////////////////////////////
 240
 241 /////////////////////////////////////////
 242 EFrameworkunifiedStatus McJoinChild(HANDLE hChildApp);
 243 /////////////////////////////////////////
 244
 245 /////////////////////////////////////////
 246 EFrameworkunifiedStatus McGetChildThreadPriority(HANDLE hChildApp, PSI_32 threadPrio);
 247 /////////////////////////////////////////
 248
 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
 276 ///        - none
 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
 294 ///        return.
 295 ///        It will block until getting message from message queue.
 296 /// \~english @par
 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.
 299 /// \~english @par
 300 ///        Since data is exchanged only in the message queue, the data size that can be received is up to 4096 bytes.
 301 /// \~english @par
 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
 305 ///          Public
 306 /// \~english @par Type
 307 ///          Sync only
 308 /// \~english @see McOpenReceiver, McSend
 309 ////////////////////////////////////////////////////////////////////////////////////////////
 310 EFrameworkunifiedStatus McReceive(HANDLE hMessage, PSTR source, UI_32 *cmd, UI_32 length, PVOID data);
 311
 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
 341 ///        - none
 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.
 362 /// \~english @par
 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.
 365 /// \~english @par
 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
 369 ///          Public
 370 /// \~english @par Type
 371 ///          Sync only
 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);
 376
 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
 384 /// \~english @par
 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
 389 ///        - none
 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.
 395 /// \~english @par
 396 ///        This API does not distinguish between error and no data.
 397 /// \~english @par
 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
 402 ///          Public
 403 /// \~english @par Type
 404 ///          Sync only
 405 /// \~english @see McReceive, McReceiveWithSession, McGetDataOfSize
 406 ////////////////////////////////////////////////////////////////////////////////////////////
 407 UI_32 McGetLength(PVOID data);
 408
 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
 419 ///        - none
 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.
 424 /// \~english @par
 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
 433 ///          Public
 434 /// \~english @par Type
 435 ///          Sync only
 436 /// \~english @see McReceive, McReceiveWithSession, McGetDataOfSize
 437 ////////////////////////////////////////////////////////////////////////////////////////////
 438 PVOID McGetDataPointer(PVOID data);
 439
 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
 462 ///        - none
 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.
 475 /// \~english @par
 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
 481 ///          Public
 482 /// \~english @par Type
 483 ///          Sync only
 484 /// \~english @see McGetLength
 485 ////////////////////////////////////////////////////////////////////////////////////////////
 486 EFrameworkunifiedStatus McGetDataOfSize(PVOID data, PVOID to, UI_32 uiSize);
 487
 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
 510 ///        - none
 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.
 523 /// \~english @par
 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
 529 ///        Public
 530 /// \~english @par Type
 531 ///        Sync only
 532 /// \~english @see
 533 ///        McReceive
 534 ////////////////////////////////////////////////////////////////////////////////////////////
 535 EFrameworkunifiedStatus McGetDataOfSizeWithSMRetain(PVOID data, PVOID to, UI_32 uiSize);
 536
 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
 552 ///        - none
 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".
 560 /// \~english @par
 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
 567 ///          Public
 568 /// \~english @par Type
 569 ///          Sync only
 570 /// \~english @see McReceive, McReceiveWithSession
 571 ////////////////////////////////////////////////////////////////////////////////////////////
 572 EFrameworkunifiedStatus McGetSysInfoData(PVOID data, PVOID to);
 573
 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
 589 ///        - none
 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
 600 ///          Public
 601 /// \~english @par Type
 602 ///          Sync only
 603 /// \~english @see McReceive, McReceiveWithSession
 604 ////////////////////////////////////////////////////////////////////////////////////////////
 605 EFrameworkunifiedStatus McClearData(PVOID data);
 606
 607 ////////////////////////////////////////////////////////////////////////////////////////////
 608 /// \ingroup McSend
 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
 637 ///        - none
 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.
 658 /// \~english @par
 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.
 661 /// \~english @par
 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.
 665 /// \~english @par
 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
 674 ///          Public
 675 /// \~english @par Type
 676 ///          Sync only
 677 /// \~english @see McOpenSender, McSendWithSession, McReceive
 678 ////////////////////////////////////////////////////////////////////////////////////////////
 679 EFrameworkunifiedStatus McSend(HANDLE hMessage, PCSTR source, UI_32 cmd, UI_32 length, PCVOID data);
 680
 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
 713 ///        - none
 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.
 732 /// \~english @par
 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.
 735 /// \~english @par
 736 ///       Command ID must be within the range PROTOCOL_FRAMEWORKUNIFIED_BASE_CMD(0x10) to PROTOCOL_FRAMEWORKUNIFIED_MAX_CMD(0xFFFFFFF0).
 737 /// \~english @par
 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
 748 ///          Public
 749 /// \~english @par Type
 750 ///          Sync only
 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);
 754
 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
 775 ///        none
 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.
 789 /// \~english @par
 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.
 792 /// \~english @par
 793 ///       Command ID must be within the range PROTOCOL_FRAMEWORKUNIFIED_BASE_CMD(0x10) to PROTOCOL_FRAMEWORKUNIFIED_MAX_CMD(0xFFFFFFF0).
 794 /// \~english @par
 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).
 804 /// \~english @par
 805 /// \~english @par Classification
 806 ///        Public
 807 /// \~english @par Type
 808 ///        Sync only
 809 /// \~english @see
 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);
 814
 815 // EFrameworkunifiedStatus McSendWithPriorityWithSession(HANDLE hMessage, PCSTR source, UI_32 cmd, UI_32 length, PCVOID data,
 816 // EFrameworkunifiedMessagePriorties priority, UI_32 sessionid);
 817
 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
 859 ///        - none
 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
 907 ///        argument. \n
 908 ///        As it is a synchronous function, after sending a message, the sender will wait until getting response form
 909 ///        receiver.
 910 ///        After receiving the response, set responseData with the received data and return.
 911 /// \~english @par
 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.
 914 /// \~english @par
 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.
 918 /// \~english @par
 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).
 921 /// \~english @par
 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
 937 ///          Public
 938 /// \~english @par Type
 939 ///          Sync only
 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);
 944
 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
 978 ///        - none
 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)
 997 /// \~english @par
 998 ///        This API applies communication function(using message queue)between processes to the application which do not
 999 ///        use
1000 ///        Dispatcher of NS Framework
1001 /// \~english @par
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
1010 ///          Public
1011 /// \~english @par Type
1012 ///          Sync only
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,
1016                               PCVOID data);
1017
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
1034 ///        - none
1035 /// \~english @par Change of internal status
1036 ///        - none
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
1045 /// \~english @par
1046 ///        cautions when using this API:
1047 ///        - the synchronous communication MQ name(invokerName) buffer size should be larger than the length of source
1048 ///        application
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
1054 ///          Public
1055 /// \~english @par Type
1056 ///          Sync only
1057 /// \~english @see McOpenSyncReceiver
1058 ////////////////////////////////////////////////////////////////////////////////////////////
1059 EFrameworkunifiedStatus McCreateInvokerName(PCSTR source, UI_32 sessionid, PSTR invokerName, UI_32 size);
1060
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
1074 ///        - none
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
1084 ///          Public
1085 /// \~english @par Type
1086 ///          Sync only
1087 /// \~english @see McOpenSender, McOpenReceiver, McOpenSyncReceiver
1088 ////////////////////////////////////////////////////////////////////////////////////////////
1089 EFrameworkunifiedStatus McClose(HANDLE hMessage);
1090
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
1101 ///        none
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
1112 ///        Public
1113 /// \~english @par Type
1114 ///        Sync only
1115 /// \~english @see
1116 //         FrameworkunifiedGetDataUSID, FrameworkunifiedForwardMessage
1117 //////////////////////////////////////////////////////////////////////////////////////////////
1118 TMemID McGetDataUSID(PVOID pData);
1119
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
1131 ///        none
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
1142 ///        Public
1143 /// \~english @par Type
1144 ///        Sync only
1145 /// \~english @see
1146 //         frameworkunifiedSendSyncResponse, frameworkunifiedProcessSyncResponse
1147 //////////////////////////////////////////////////////////////////////////////////////////////
1148 PCSTR McGetMsgSrc(PVOID data);
1149
1150
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
1168 ///        none
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
1180 ///       Message.
1181 /// \~english @par Classification
1182 ///        Public
1183 /// \~english @par Type
1184 ///        Sync only
1185 /// \~english @see
1186 //         FrameworkunifiedForwardMessage
1187 //////////////////////////////////////////////////////////////////////////////////////////////
1188 EFrameworkunifiedStatus McForward(HANDLE hMessage, PCSTR source, UI_32 iCmd, TMemID USID);
1189
1190
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
1201 ///        - none
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
1209 ///          Public
1210 /// \~english @par Type
1211 ///          Sync only
1212 /// \~english @see McOpenSender, McOpenReceiver, McOpenSyncReceiver
1213 ////////////////////////////////////////////////////////////////////////////////////////////
1214 void McFlushReceiver(HANDLE hMessage);
1215
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
1227 ///        - none
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
1235 /// \~english @par
1236 ///        This API applies communication function(using message queue)between processes to the application which do not
1237 ///        use
1238 ///        Dispatcher of NS Framework
1239 /// \~english @par Classification
1240 ///          Public
1241 /// \~english @par Type
1242 ///          Sync only
1243 /// \~english @see McOpenReceiver, McOpenSender
1244 ////////////////////////////////////////////////////////////////////////////////////////////
1245 PCSTR McGetQueueName(HANDLE hMessage);
1246
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
1257 ///        - none
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
1265 /// \~english @par
1266 ///        This API applies communication function(using message queue)between processes to the application which do not
1267 ///        use
1268 ///        Dispatcher of NS Framework
1269 /// \~english @par Classification
1270 ///          Public
1271 /// \~english @par Type
1272 ///          Sync only
1273 /// \~english @see McOpenReceiver, McOpenSender
1274 ////////////////////////////////////////////////////////////////////////////////////////////
1275 int McGetQueueFD(HANDLE hMessage);
1276
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
1284 /// \~english @par
1285 ///        EFrameworkunifiedStatus Enum
1286 /// \~english @code
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;
1335 ///            @endcode
1336 /// \~english @par Preconditons
1337 ///        none
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
1348 ///        Public
1349 /// \~english @par Type
1350 ///        Sync only
1351 /// \~english @see
1352 //         none
1353 //////////////////////////////////////////////////////////////////////////////////////////////
1354 EFrameworkunifiedStatus McTranslateError(int error);
1355
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
1374 ///        - none
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
1385 /// \~english @par
1386 ///       CMD ID should be in (PROTOCOL_FRAMEWORKUNIFIED_BASE_CMD(0x10) to PROTOCOL_FRAMEWORKUNIFIED_MAX_CMD(0xFFFFFFF0))
1387 /// \~english @par
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
1391 ///          Public
1392 /// \~english @par Type
1393 ///          Sync only
1394 /// \~english @see McZcGetBuf, McZcSend
1395 ////////////////////////////////////////////////////////////////////////////////////////////
1396 EFrameworkunifiedStatus McZcSetParam(HANDLE handle, UI_32 cmd, UI_32 length);
1397
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
1409 ///        - none
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
1417 /// \~english @par
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
1421 ///          Public
1422 /// \~english @par Type
1423 ///          Sync only
1424 /// \~english @see McZcGetBuf
1425 ////////////////////////////////////////////////////////////////////////////////////////////
1426 PVOID McZcGetBuf(HANDLE handle);
1427
1428 ////////////////////////////////////////////////////////////////////////////////////////////
1429 /// \ingroup McZcSend
1430 /// \~english @par Brief
1431 ///       send message
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
1446 ///        - none
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
1461 ///          Public
1462 /// \~english @par Type
1463 ///          Method
1464 /// \~english @see McZcOpenSender, McZcSetParam, McZcGetBuf
1465 ////////////////////////////////////////////////////////////////////////////////////////////
1466 EFrameworkunifiedStatus McZcSend(HANDLE hMessage);
1467
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
1477 ///        - none
1478 /// \~english @par Change of internal status
1479 ///        - none
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
1491 ///          Public
1492 /// \~english @par Type
1493 ///          Sync only
1494 /// \~english @see McZcSetParam, McZcGetBuf, McZcSend, McZcClose
1495 ////////////////////////////////////////////////////////////////////////////////////////////
1496 HANDLE McZcOpenSender(PCSTR source);
1497
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
1511 ///        - none
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
1521 ///          Public
1522 /// \~english @par Type
1523 ///          Sync only
1524 /// \~english @see McZcOpenSender
1525 ////////////////////////////////////////////////////////////////////////////////////////////
1526 EFrameworkunifiedStatus McZcClose(HANDLE handle);
1527
1528 #ifdef __cplusplus
1529 }
1530 #endif
1531 #endif /* __NATIVESERVICES_MESSAGE_CENTER_IF_H__ */  // NOLINT  (build/header_guard)
1532 /** @}*/
1533 /** @}*/
1534 /** @}*/
1535 /** @}*/
1536 //@}