nsframework/framework_unified/client/NS_MessageQueue/include/ns_msg_queue.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 ns_msg_queue.h
  19  * @brief \~english TestFramework provides interface for implementing functional test classes.
  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 #ifndef FRAMEWORK_UNIFIED_CLIENT_NS_MESSAGEQUEUE_INCLUDE_NS_MSG_QUEUE_H_
  34 #define FRAMEWORK_UNIFIED_CLIENT_NS_MESSAGEQUEUE_INCLUDE_NS_MSG_QUEUE_H_
  35
  36 #include <native_service/frameworkunified_types.h>
  37
  38
  39 #ifdef __cplusplus
  40 extern "C" {
  41 #endif
  42
  43 /// \brief Enum that defines the value Q Types
  44 typedef enum eQType {
  45   eQTypeReveiver,
  46   eQTypeSender,
  47   eQTypeInvld
  48 } EQType;
  49
  50 // PASA CCR IPC Framework API
  51
  52 ////////////////////////////////////////////////////////////////////////////////////////////
  53 /// OpenReceiver
  54 /// The opens a handle to a Receiver message queue.
  55 ///
  56 /// \param [in] name
  57 ///         PCSTR - name of the message queue you want to receiver messages on
  58 ///
  59 /// \return HANDLE
  60 ///         handle - to a recevier's message queue
  61 ///     INVALID_HANDLE - Either message name is NULL or length is >= MAX_QUEUE_NAME_SIZE
  62 ///     INVALID_HANDLE - or an error occurred while opening a queue
  63 ////////////////////////////////////////////////////////////////////////////////////////////
  64 HANDLE OpenReceiver(PCSTR name);
  65
  66 ////////////////////////////////////////////////////////////////////////////////////////////
  67 /// OpenReceiverNotBlocked
  68 /// The opens a handle to a Receiver message queue. Operations on this queue
  69 /// are non-blocking if queue is empty or full.
  70 ///
  71 /// \param [in] name
  72 ///         PCSTR - name of the message queue you want to receiver messages on
  73 ///
  74 /// \return HANDLE
  75 ///         handle - to a recevier's message queue
  76 ///     INVALID_HANDLE - Either message name is NULL or length is >= MAX_QUEUE_NAME_SIZE
  77 ///     INVALID_HANDLE - or an error occurred while opening a queue
  78 ////////////////////////////////////////////////////////////////////////////////////////////
  79 HANDLE OpenReceiverNotBlocked(PCSTR name);
  80
  81 ////////////////////////////////////////////////////////////////////////////////////////////
  82 /// OpenSyncReceiver
  83 /// The opens a handle to a response Receiver message queue.
  84 ///
  85 /// \param [in] name
  86 ///         PCSTR - name of the message queue you want to receiver messages on
  87 ///
  88 /// \return HANDLE
  89 ///         handle - to a recevier's message queue
  90 ///     INVALID_HANDLE - Either message name is NULL or length is >= MAX_QUEUE_NAME_SIZE
  91 ///     INVALID_HANDLE - or an error occurred while opening a queue
  92 ////////////////////////////////////////////////////////////////////////////////////////////
  93 HANDLE openSyncReceiver(PCSTR name);
  94
  95 ////////////////////////////////////////////////////////////////////////////////////////////
  96 /// OpenSender
  97 /// The opens a handle for sending messages to another message queue.
  98 ///
  99 /// \param [in] name
 100 ///         PCSTR - name of the message queue you want to send messages too
 101 ///
 102 /// \return HANDLE
 103 ///         handle - senders message queue handle
 104 ///     INVALID_HANDLE - Either message name is NULL or length is >= MAX_QUEUE_NAME_SIZE
 105 ///     INVALID_HANDLE - or an error occurred while opening a queue
 106 ////////////////////////////////////////////////////////////////////////////////////////////
 107 HANDLE OpenSender(PCSTR name);
 108
 109 ////////////////////////////////////////////////////////////////////////////////////////////
 110 /// openSyncSender
 111 /// The opens a handle for sending response to another message queue.
 112 ///
 113 /// \param [in] name
 114 ///         PCSTR - name of the message queue you want to send messages too
 115 ///
 116 /// \return HANDLE
 117 ///         handle - senders message queue handle
 118 ///     INVALID_HANDLE - Either message name is NULL or length is >= MAX_QUEUE_NAME_SIZE
 119 ///     INVALID_HANDLE - or an error occurred while opening a queue
 120 ////////////////////////////////////////////////////////////////////////////////////////////
 121 HANDLE openSyncSender(PCSTR name);
 122
 123 ////////////////////////////////////////////////////////////////////////////////////////////
 124 /// openSenderZc
 125 /// The opens a handle for sending response to another message queue.
 126 ///
 127 /// \param [in] name
 128 ///         PCSTR - name of the message queue you want to send messages too
 129 ///
 130 /// \return HANDLE
 131 ///         handle - senders message queue handle
 132 ///     INVALID_HANDLE - Either message name is NULL or length is >= MAX_QUEUE_NAME_SIZE
 133 ///     INVALID_HANDLE - or an error occurred while opening a queue
 134 ////////////////////////////////////////////////////////////////////////////////////////////
 135 HANDLE openSenderZc(PCSTR name);
 136
 137 /////////////////////////////////////////
 138 #include <pthread.h>
 139 HANDLE OpenSenderChild(PCSTR name, pthread_t threadid);
 140 /////////////////////////////////////////
 141
 142 /////////////////////////////////////////
 143 EFrameworkunifiedStatus JoinChild(HANDLE hChildApp);
 144 /////////////////////////////////////////
 145
 146 /////////////////////////////////////////
 147 EFrameworkunifiedStatus GetChildThreadPriority(HANDLE hChildApp, PSI_32 threadPrio);
 148 /////////////////////////////////////////
 149
 150
 151 ////////////////////////////////////////////////////////////////////////////////////////////
 152 /// SendMessage
 153 /// The function sends a message to a queue.
 154 ///
 155 /// \param [in] hMessage
 156 ///         Handle - handle to the sendMessage, OpenSender
 157 /// \param [in] length
 158 ///          UI_32 -  length of the data to be sent
 159 /// \param [in] data
 160 ///          const void* - pointer to the data that needs to be transmitted
 161 ///
 162 /// \return EFrameworkunifiedaStatus
 163 ///         status - status of the message(error)
 164 ////////////////////////////////////////////////////////////////////////////////////////////
 165 EFrameworkunifiedStatus SendMessage(HANDLE hMessage, UI_32 length, PVOID data);
 166
 167 ////////////////////////////////////////////////////////////////////////////////////////////
 168 /// SendMessageWithPriority
 169 /// The function sends a message to a queue.
 170 ///
 171 /// \param [in] hMessage
 172 ///         Handle - handle to the sendMessage, OpenSender
 173 /// \param [in] length
 174 ///          UI_32 -  length of the data to be sent
 175 /// \param [in] data
 176 ///          const void* - pointer to the data that needs to be transmitted
 177 /// \param [in] priority
 178 ///          EFrameworkunifiedMessagePriorties - priority at which the message should be sent at!
 179 ///
 180 /// \return EFrameworkunifiedaStatus
 181 ///         status - status of the message(error)
 182 ////////////////////////////////////////////////////////////////////////////////////////////
 183 EFrameworkunifiedStatus SendMessageWithPriority(HANDLE hMessage, UI_32 length, PVOID data, EFrameworkunifiedMessagePriorties priority);
 184
 185 ////////////////////////////////////////////////////////////////////////////////////////////
 186 /// ReceiveMessage
 187 /// The function blocks on a message queue waiting for data to be received.
 188 ///
 189 /// \param [in] hMessage
 190 ///         HANDLE - handle to the recvMessage, OpenReceiver
 191 /// \param [in] length
 192 ///          UI_32 -  length of the data buffer provided
 193 /// \param [in] data
 194 ///          void* -  pointer to the data to be received
 195 ///
 196 /// \return SI_32
 197 ///         length read - indicates the number of bytes that were read from the queue (eFrameworkunifiedStatusErrOther) error
 198 ////////////////////////////////////////////////////////////////////////////////////////////
 199 SI_32  ReceiveMessage(HANDLE hMessage, UI_32 length, PVOID data);
 200
 201 ////////////////////////////////////////////////////////////////////////////////////////////
 202 /// CloseReceiver
 203 /// The closes a connection to a Receiver message queue.
 204 ///
 205 /// \param [in] hMessage
 206 ///         HANDLE - handle to the recvMessage that will be closed
 207 ///
 208 /// \return EFrameworkunifiedaStatus
 209 ///         status - indicates if the close was successfully (eFrameworkunifiedStatusOK) or not (anything else)
 210 ////////////////////////////////////////////////////////////////////////////////////////////
 211 EFrameworkunifiedStatus CloseReceiver(HANDLE handle);
 212
 213 ////////////////////////////////////////////////////////////////////////////////////////////
 214 /// CloseReceiver
 215 /// The closes a connection to a Receiver message queue.
 216 ///
 217 /// \param [in] hMessage
 218 ///         HANDLE - handle to the recvMessage that will be closed
 219 ///
 220 /// \return EFrameworkunifiedaStatus
 221 ///          status - indicates if the close was successfully (eFrameworkunifiedStatusOK) or not (anything else)
 222 ////////////////////////////////////////////////////////////////////////////////////////////
 223 EFrameworkunifiedStatus CloseSender(HANDLE handle);
 224
 225
 226 ////////////////////////////////////////////////////////////////////////////////////////////
 227 /// Flush
 228 /// Flush all data on HANDLE's Receiver message queue.
 229 ///
 230 /// \param [in] hMessage
 231 ///         HANDLE - handle to the recvMessage queue that will be flushed
 232 ///
 233 /// \return void
 234 ////////////////////////////////////////////////////////////////////////////////////////////
 235 void Flush(HANDLE hMessage);
 236
 237 ////////////////////////////////////////////////////////////////////////////////////////////
 238 /// GetQueueType
 239 /// Get the handle's queue type.
 240 ///
 241 /// \param [in] hMessage
 242 ///         HANDLE - handle to the Message queue
 243 ///
 244 /// \return EQType
 245 ///     EQType - queue type of handle
 246 ////////////////////////////////////////////////////////////////////////////////////////////
 247 EQType GetQueueType(HANDLE hMessage);
 248
 249 ////////////////////////////////////////////////////////////////////////////////////////////
 250 //  Function : TranslateError
 251 //  Translates global error variables into FW EFrameworkunifiedStatus
 252 ///
 253 /// \param [in] error
 254 ///         int - error variable
 255 ///
 256 /// \return EFrameworkunifiedStatus
 257 ///     EFrameworkunifiedStatus - frameworkunified error type
 258 ////////////////////////////////////////////////////////////////////////////////////////////
 259 EFrameworkunifiedStatus TranslateError(int error);
 260
 261 ////////////////////////////////////////////////////////////////////////////////////////////
 262 /// GetQueueName
 263 /// This gets the name of the message queue
 264 ///
 265 /// \param [in] hMessage
 266 ///         HANDLE - handle of the message queue
 267 ///                  (handle created with McOpenReceiver or McOpenSender)
 268 ///
 269 /// \return PCSTR
 270 ///         name - name of the message queue if handle is valid else NULL
 271 ////////////////////////////////////////////////////////////////////////////////////////////
 272 PCSTR GetQueueName(HANDLE hMessage);
 273
 274 ////////////////////////////////////////////////////////////////////////////////////////////
 275 /// GetQueueFD
 276 /// This gets the fd of the message queue
 277 ///
 278 /// \param [in] hMessage
 279 ///         HANDLE - handle of the message queue
 280 ///                  (handle created with McOpenReceiver or McOpenSender)
 281 ///
 282 /// \return int
 283 ///         fd - fd of the message queue if handle is valid else -1
 284 ////////////////////////////////////////////////////////////////////////////////////////////
 285 int GetQueueFD(HANDLE hMessage);
 286
 287 #ifdef __cplusplus
 288 }
 289 #endif
 290
 291 #endif  // FRAMEWORK_UNIFIED_CLIENT_NS_MESSAGEQUEUE_INCLUDE_NS_MSG_QUEUE_H_
 292
 293 /** @}*/
 294 /** @}*/
 295 /** @}*/