This ticket is for implementing a tunneling API that can be used to tunnel
NUL-terminated strings through the old SaNameT type.
Ticket [#886] and [#873] are for adding support for long DN tunneling in IMM
and NTF, respectively. Ticket [#643] is for adding a new SaStringT based API
to the IMM that will also by default support long DNs.
The tunneling API is defined below:
The SaNameT type is deprecated will be replaced with string parameters in new SAF APIs. As an intermediate solution, the extended format of the SaNameT type can be used to pass string parameters to and from old SAF APIs as well, by tunneling them through the SaNameT type. To enable the extended SaNameT format, the application source code has to be compiled with the SA_EXTENDED_NAME_SOURCE preprocessor macro defined, and the environment variable SA_ENABLE_EXTENDED_NAMES must be set to the value 1 before the first call to any SAF API function.
When the extended SaNameT format is enabled, the SA_MAX_NAME_LENGTH constant must not be used, and the application must treat the SaNameT type as opaque and not access any of its members directly. Instead, the saAisNameLend() and saAisNameBorrow() access functions shall be used. The SA_MAX_UNEXTENDED_NAME_LENGTH constant can be used to refer to the maximum string length that can be stored in the unextended SaNameT type.
#ifdef SA_EXTENDED_NAME_SOURCE #define SA_MAX_UNEXTENDED_NAME_LENGTH 256 #endif /* SA_EXTENDED_NAME_SOURCE */
#ifdef SA_EXTENDED_NAME_SOURCE void saAisNameLend( SaConstStringT value, SaNameT* name); #endif /* SA_EXTENDED_NAME_SOURCE */
value - [in] A pointer to a NUL-terminated string that will be tunneled through the SaNameT type.
name - [out] A pointer to an SaNameT type to be used for tunneling.
Tunnel a NUL-terminated string through a SaNameT type. If length of the string is strictly less than SA_MAX_UNEXTENDED_NAME_LENGTH bytes, the contents of the string is copied into the SaNameT type and can be read in a backwards compatible way by legacy applications that do not support the extended SaNameT format. If length of the string is greater than or equal to SA_MAX_UNEXTENDED_NAME_LENGTH, no copying is performed. Instead, a reference to the original string is stored in the SaNameT type. In this case, it is therefore important that the original string is not modified or freed for as long as the SaNameT type may still used.
#ifdef SA_EXTENDED_NAME_SOURCE SaConstStringT saAisNameBorrow( const SaNameT* name); #endif /* SA_EXTENDED_NAME_SOURCE */
name - [in] A pointer to an SaNameT type that has been previously set using the saAisNameLend() function.
Retrieve a tunneled string from an SaNameT type. Before calling this function, the SaNameT stucture must have been initialized either by a call to the saAisNameLend() function or by being used as an output parameter of any other SAF API function. If the length of the returned string is strictly less than SA_MAX_UNEXTENDED_NAME_LENGTH bytes, the returned pointer points to a copy of the string stored inside the SaNameT type. Otherwise, the returned pointer is equal to the original string pointer that was passed as a parameter to the saAisNameLend() function.
A pointer to a NUL-terminated string, or a NULL pointer in case of a failure.