"Fossies" - the Fresh Open Source Software Archive

Member "opensaf-5.21.09/src/ais/aisa_api.c" (14 Sep 2021, 6506 Bytes) of package /linux/misc/opensaf-5.21.09.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "aisa_api.c" see the Fossies "Dox" file reference documentation and the latest Fossies "Diffs" side-by-side code changes report: 5.21.06_vs_5.21.09.

    1 /*  -*- OpenSAF  -*-
    2  *
    3  * (C) Copyright 2014 The OpenSAF Foundation
    4  *
    5  * This program is distributed in the hope that it will be useful, but
    6  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
    7  * or FITNESS FOR A PARTICULAR PURPOSE. This file and program are licensed
    8  * under the GNU Lesser General Public License Version 2.1, February 1999.
    9  * The complete license can be accessed from the following location:
   10  * http://opensource.org/licenses/lgpl-license.php
   11  * See the Copying file included with the OpenSAF distribution for full
   12  * licensing terms.
   13  *
   14  * Author(s): Ericsson AB
   15  *
   16  */
   17 
   18 /*****************************************************************************
   19   DESCRIPTION:
   20 
   21   The SaNameT type is deprecated will be replaced with string parameters in new
   22   SAF APIs. As an intermediate solution, the extended format of the SaNameT type
   23   can be used to pass string parameters to and from old SAF APIs as well, by
   24   tunneling them through the SaNameT type. To enable the extended SaNameT
   25   format, the application source code has to be compiled with the
   26   SA_EXTENDED_NAME_SOURCE preprocessor macro defined, and the environment
   27   variable SA_ENABLE_EXTENDED_NAMES must be set to the value 1 before the first
   28   call to any SAF API function.
   29 
   30   When the extended SaNameT format is enabled, the SA_MAX_NAME_LENGTH constant
   31   must not be used, and the application must treat the SaNameT type as opaque
   32   and not access any of its members directly. Instead, the saAisNameLend() and
   33   saAisNameBorrow() access functions shall be used. The
   34   SA_MAX_UNEXTENDED_NAME_LENGTH constant can be used to refer to the maximum
   35   string length that can be stored in the unextended SaNameT type.
   36 
   37 *****************************************************************************/
   38 
   39 #ifndef SA_EXTENDED_NAME_SOURCE
   40 #define SA_EXTENDED_NAME_SOURCE
   41 #endif
   42 #include <saAis.h>
   43 #include <stddef.h>
   44 #include <stdbool.h>
   45 #include "base/osaf_extended_name.h"
   46 #include "base/logtrace.h"
   47 #include "base/saf_error.h"
   48 
   49 static void ais_name_lend(SaConstStringT value, SaNameT *name);
   50 static SaConstStringT ais_name_borrow(const SaNameT *name);
   51 static SaConstStringT ais_error_str(SaAisErrorT error_number);
   52 
   53 /****************************************************************************
   54   Name      :  saAisNameLend
   55 
   56   Description   :  Tunnel a NUL-terminated string through a SaNameT type. If
   57            length of the string is strictly less than
   58            SA_MAX_UNEXTENDED_NAME_LENGTH bytes, the contents of the
   59            string is copied into the SaNameT type and can be read in a
   60            backwards compatible way by legacy applications that do not
   61            support the extended SaNameT format. If length of the string
   62            is greater than or equal to SA_MAX_UNEXTENDED_NAME_LENGTH, no
   63            copying is performed. Instead, a reference to the original
   64            string is stored in the SaNameT type. In this case, it is
   65            therefore important that the original string is not modified
   66            or freed for as long as the SaNameT type may still used.
   67 
   68   Arguments :  value [in] - A pointer to a NUL-terminated string that will
   69                 be tunneled through the SaNameT type.
   70 
   71            name [out] - A pointer to an SaNameT type to be used for
   72                 tunneling.
   73 
   74   Return Values :
   75 
   76   Notes     :
   77 ******************************************************************************/
   78 void saAisNameLend(SaConstStringT value, SaNameT *name)
   79     __attribute__((weak, alias("ais_name_lend")));
   80 
   81 /****************************************************************************
   82   Name      :  saAisNameBorrow
   83 
   84   Description :    Retrieve a tunneled string from an SaNameT type. Before
   85            calling this function, the SaNameT stucture must have been
   86            initialized either by a call to the saAisNameLend() function
   87            or by being used as an output parameter of any other SAF API
   88            function. If the length of the returned string is strictly
   89            less than SA_MAX_UNEXTENDED_NAME_LENGTH bytes, the returned
   90            pointer points to a copy of the string stored inside the
   91            SaNameT type. Otherwise, the returned pointer is equal to the
   92            original string pointer that was passed as a parameter to the
   93            saAisNameLend() function.
   94 
   95   Arguments :  name [in] -  A pointer to an SaNameT type that has been
   96                 previously set using the saAisNameLend()
   97                 function.
   98 
   99   Return Values :  A pointer to a NUL-terminated string, or a NULL pointer in
  100            case of a failure.
  101 
  102   Notes     :
  103 ******************************************************************************/
  104 SaConstStringT saAisNameBorrow(const SaNameT *name)
  105     __attribute__((weak, alias("ais_name_borrow")));
  106 
  107 /****************************************************************************
  108  * Name      :  saAisStrError
  109  *
  110  * Description   :  A function to return human readable error strings for
  111  *         AIS error number.
  112  *
  113  * Arguments     :  error_number [in] - AIS error number
  114  *
  115  * Return Values : Error strings for AIS error number.
  116  *
  117  * Notes     :
  118  ******************************************************************************/
  119 SaConstStringT saAisStrError(SaAisErrorT error_number)
  120     __attribute__((weak, alias("ais_error_str")));
  121 
  122 // cppcheck-suppress unusedFunction
  123 void ais_name_lend(SaConstStringT value, SaNameT *name)
  124 {
  125     osaf_extended_name_lend(value, name);
  126 }
  127 
  128 // cppcheck-suppress unusedFunction
  129 SaConstStringT ais_name_borrow(const SaNameT *name)
  130 {
  131     SaConstStringT value = osaf_extended_name_borrow(name);
  132     size_t length = name->_opaque[0];
  133     if (length != kOsafExtendedNameMagic) {
  134         /*
  135          * Check that the string inside SaNameT is properly
  136          * NUL-terminated. If not, we return a NULL pointer. We allow
  137          * the terminating NUL character to be counted in the length
  138          * field, as this is a common mistake and still makes the string
  139          * NUL-terminated (although with a length that is different from
  140          * what the length field says).
  141          *
  142          * The reason for performing this check is that a C string MUST
  143          * be NUL terminated, but the legacy SaNameT type did not
  144          * require the string stored in the value field to be NUL
  145          * terminated. It will always be NUL terminated if the SaNameT
  146          * was set using the saAisNameLend() function, but potentially
  147          * we could be passed an SaNameT that was set using legacy code.
  148          */
  149         bool valid = length < SA_MAX_UNEXTENDED_NAME_LENGTH &&
  150                  value[length] == '\0';
  151         if (!valid)
  152             value = NULL;
  153     }
  154     return value;
  155 }
  156 
  157 // cppcheck-suppress unusedFunction
  158 SaConstStringT ais_error_str(SaAisErrorT error_number)
  159 {
  160     return (SaConstStringT)saf_error(error_number);
  161 }