video_in_hal/nsframework/framework_unified/client/include/native_service/ns_shared_mem_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 ns_shared_mem_if.h
  19  * @brief \~english API Header for Logger.
  20  *                                      Declares the external APIs to Logger.
  21  *
  22  */
  23 /** @addtogroup BaseSystem
  24  *  @{
  25  */
  26 /** @addtogroup native_service
  27  *  @ingroup BaseSystem
  28  *  @{
  29  */
  30 /** @addtogroup framework_unified
  31  *  @ingroup native_service
  32  *  @{
  33  */
  34 /** @addtogroup native
  35  *  @ingroup framework_unified
  36  *  @{
  37  */
  38 #ifndef __CCR_NATIVESERVICES_MESSAGECENTER_NSSHAREDMEMIF_H__  // NOLINT  (build/header_guard)
  39 #define __CCR_NATIVESERVICES_MESSAGECENTER_NSSHAREDMEMIF_H__
  40
  41 #ifdef __cplusplus
  42 extern "C" {
  43 #endif
  44
  45 #include <native_service/frameworkunified_types.h>  ///< Standard Types
  46
  47 typedef unsigned int TMemID;    ///< Type of memory buffer identifiers
  48 #define BAD_MEM_ID (0)
  49
  50 /////////////////////////////////////////////////////////////////////////////////////
  51 /// \ingroup SetDataToShared
  52 /// \~english @par Summary
  53 ///           - Store a large chunk of memory using SharedMem service
  54 /// \~english @param [in] data
  55 ///           - const void* - data to be stored in shared memory
  56 /// \~english @param [in] dataBytes
  57 ///           - UI_32 - length of the data (in bytes) that is stored in shared memory
  58 /// \~english @param [in] from
  59 ///           - const char * - start address
  60 /// \~english @param [in] to
  61 ///           - const char * - end address
  62 /// \~english @retval TMemID - unique MemID of the data stored in the shared memory, 0 if error occurs
  63 /// \~english @par Preconditions
  64 ///           - None
  65 /// \~english @par Change of the internal state
  66 ///           - shared memory changed
  67 /// \~english @par Causes of failures
  68 ///           - param is Invalid.[BAD_MEM_ID]
  69 /// \~english @par Classification
  70 ///           - Public
  71 /// \~english @par Type
  72 ///           - sync only
  73 /// \~english @par Detail
  74 ///           - The function sets the data to the shared memory and associates it with a\n
  75 ///             unique MemID that can be used to refer to data in subsequent calls \n
  76 ///             (not necessarily from the same process).
  77 /// \~english @par
  78 ///           - TMemID:Result
  79 ///               - Except 0:Success
  80 ///               -        0:Failure
  81 /// \~english @see  None
  82 ////////////////////////////////////////////////////////////////////////////////////
  83 TMemID SetDataToShared(const void *data, UI_32 dataBytes, const char *from, const char *to);
  84
  85 /////////////////////////////////////////////////////////////////////////////////////
  86 /// \ingroup GetDataFromShared
  87 /// \~english @par Summary
  88 ///           - Retrieve a large chunk of memory using SharedMem service
  89 /// \~english @param [in] id
  90 ///           - TMemID - MemID of the shared data
  91 /// \~english @param [in] data
  92 ///           - void*  - Buffer to store data in, must be at least as large as buffer associated with id
  93 /// \~english @param [in] dataMaxBytes
  94 ///           - UI_32  - Size of data - system will never copy more than dataMaxBytes bytes into data
  95 /// \~english @retval eFrameworkunifiedStatusOK Success
  96 /// \~english @retval eFrameworkunifiedStatusInvldParam Invalid parameter
  97 /// \~english @retval eFrameworkunifiedStatusInvldID Invalid id
  98 /// \~english @retval eFrameworkunifiedStatusFail Some sort of error occurred
  99 /// \~english @par Preconditions
 100 ///           -
 101 /// \~english @par Change of the internal state
 102 ///           - None
 103 /// \~english @par Causes of failures
 104 ///           - param is Invalid. [eFrameworkunifiedStatusInvldParam]
 105 ///           - id is Invalid. [eFrameworkunifiedStatusInvldID]
 106 ///           - Any error has occurred at the time of transmission of the System Manager message for the session.
 107 ///           [eFrameworkunifiedStatusFail]
 108 /// \~english @par Classification
 109 ///           - Public
 110 /// \~english @par Type
 111 ///           - sync only
 112 /// \~english @par Detail
 113 ///           - Retrieve data, given a MemID. Each MemID is only safe to use until a call to \n
 114 ///             DiscardDataFromShared If the call succeeds, the return value is eFrameworkunifiedStatusOK.\n
 115 ///             Otherwise, the contents of data are undefined.
 116 /// \~english @par
 117 ///           - eFrameworkunifiedStatus:Result
 118 ///               - eFrameworkunifiedStatusOK:Success
 119 ///               - Except eFrameworkunifiedStatusOK:Failure
 120 /// \~english @see  None
 121 ////////////////////////////////////////////////////////////////////////////////////
 122 EFrameworkunifiedStatus GetDataFromShared(TMemID id, void *data, UI_32 dataMaxBytes);
 123
 124 /////////////////////////////////////////////////////////////////////////////////////
 125 /// \ingroup GetLengthOfDataFromShared
 126 /// \~english @par Summary
 127 ///           - Query the minimum buffer size, in bytes, necessary to hold a chunk of memory in SharedMem
 128 /// \~english @param [in] id
 129 ///           - TMemID - MemID of the shared data
 130 /// \~english @retval length - Minimum buffer size, in bytes, required to hold the data associated with id.
 131 /// \~english @par Preconditions
 132 ///           -
 133 /// \~english @par Change of the internal state
 134 ///           - None
 135 /// \~english @par Causes of failures
 136 ///           - param is Invalid.[BAD_MEM_ID]
 137 /// \~english @par Classification
 138 ///           - Public
 139 /// \~english @par Type
 140 ///           - sync only
 141 /// \~english @par Detail
 142 ///           - Returns the minimum buffer size, in bytes, required to hold the data associated with id.\n
 143 ///             Return value of 0 indicates failure.For an id, may be called one or more times \n
 144 ///             until a successful call to either GetDataFromShared or DiscardDataFromShared with that id.
 145 /// \~english @par
 146 ///           - TMemID:Result
 147 ///               - Except 0:Success
 148 ///               -        0:Failure
 149 /// \~english @see  None
 150 ////////////////////////////////////////////////////////////////////////////////////
 151 UI_32 GetLengthOfDataFromShared(TMemID id);
 152
 153 /////////////////////////////////////////////////////////////////////////////////////
 154 /// \ingroup DiscardDataFromShared
 155 /// \~english @par Summary
 156 ///           - Discard a chunk of memory in SharedMem
 157 /// \~english @param [in] id
 158 ///           - TMemID - MemID of the shared data
 159 /// \~english @retval eFrameworkunifiedStatusOK - Success
 160 /// \~english @retval eFrameworkunifiedStatusInvldParam -Invalid parameter
 161 /// \~english @retval eFrameworkunifiedStatusInvldID -Invalid id
 162 /// \~english @retval eFrameworkunifiedStatusFail -Some sort of error occurred
 163 /// \~english @par Preconditions
 164 ///           -
 165 /// \~english @par Change of the internal state
 166 ///           - None
 167 /// \~english @par Causes of failures
 168 ///           - param is Invalid. [eFrameworkunifiedStatusInvldParam]
 169 ///           - id is Invalid. [eFrameworkunifiedStatusInvldID]
 170 ///           - Any error has occurred at the time of transmission of the System Manager message for the session.
 171 ///           [eFrameworkunifiedStatusFail]
 172 /// \~english @par Classification
 173 ///           - Public
 174 /// \~english @par Type
 175 ///           - sync only
 176 /// \~english @par Detail
 177 ///           - Invalidates the data stored with the MemID.  Each id is only safe to use in a\n
 178 ///             single successful call to GetDataFromShared or DiscardDataFromShared
 179 ///             If the call succeeds, the return value is eImageStatusOK.
 180 ///             On failure, the state of shared memory shall not be altered
 181 /// \~english @par
 182 ///           - eFrameworkunifiedStatus:Result
 183 ///               - eFrameworkunifiedStatusOK:Success
 184 ///               - Except eFrameworkunifiedStatusOK:Failure
 185 /// \~english @see  None
 186 ////////////////////////////////////////////////////////////////////////////////////
 187 EFrameworkunifiedStatus DiscardDataFromShared(TMemID id);
 188
 189 #ifdef __cplusplus
 190 }
 191 #endif
 192 #endif  // __CCR_NATIVESERVICES_MESSAGECENTER_NSSHAREDMEMIF_H__  // NOLINT  (build/header_guard)
 193 /** @}*/
 194 /** @}*/
 195 /** @}*/
 196 /** @}*/