- **summary**: IMM: SaNameT 256 byte size limit and RDN 64 byte size limit. -->
osaf: Extended Name Type
- Description has changed:
Diff:
~~~~
--- old
+++ new
@@ -1,73 +1,61 @@
-The SaNameT type and in particular its limit in size of 256 bytes
-is an aspect of the SAF standard that was, shall we say, not so
-well conceived.
+Ticket [#643] and [#873] are for adding SaStringT-based APIs in IMM and NTF,
respectively. This ticket is for implementing a tunneling API that can be used
to tunnel NUL-terminated strings through the old SaNameT type. The tunneling
API is defined below:
-The 256 byte limit on SaNameT implies the same limit on DN length.
-it is also the reason behind the 64 byte limit on RDN length, if the
-RDN attribute is defined on SaStringT.
+Extended Name Type
+==================
+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.
-The SaNameT type is used more or less in the APIs of practically all
-SAF services. Thus an enhancement that would try to extend it
-length would not just be an enhancement on the IMM service,
-but all services.
+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.
-This discussion topic is intended to probe the possibility of
-increasing the size of SaNameT, or of replacing SaNameT with
-a type defined in the same way as SaStringT.
-There is still a point in having a DN type, that is semantically
-distinct from SaStringT, because a DN is in essence the IMM
-reference data-type.
+Definition
+----------
+ #ifdef SA_EXTENDED_NAME_SOURCE
+
+ #define SA_MAX_UNEXTENDED_NAME_LENGTH 256
+
+ #endif /* SA_EXTENDED_NAME_SOURCE */
+
+saAisNameLend()
+===============
+Prototype
+---------
+ #ifdef SA_EXTENDED_NAME_SOURCE
+
+ void
+ saAisNameLend(
+ SaConstStringT value,
+ SaNameT* name);
+
+ #endif /* SA_EXTENDED_NAME_SOURCE */
-One possibility is to continue with SaNameT, but extend both
-its struct definition and the size limit.
-The "length" member is already defined as SaUint?16T,
-which means the length member is not the problem.
+Parameters
+----------
+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.
-Had the SAF standard been defined in C++ we could just create
-a subclass to the SaNameT class, but since we are restricted to
-the more primitive C language, one has to either create a
-completely new type SaNameT_2 or do some kind of "trick".
+Description
+-----------
+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.
-Changing the type has the big problem that it impacts so many
-APIs and in a non backwards compatible way.
+saAisNameBorrow()
+=================
+Prototype
+---------
+ #ifdef SA_EXTENDED_NAME_SOURCE
+
+ SaConstStringT
+ saAisNameBorrow(
+ const SaNameT* name);
-So I propose some form of trick.
+ #endif /* SA_EXTENDED_NAME_SOURCE */
-For example, we can exploit the 16 bit size field, in a way that
-is both backwards compatible and forwards compatible.
+Parameters
+----------
+name - [in] A pointer to an SaNameT type that has been previously set using
the saAisNameLend() function.
-Assume that if the high order bit of the length feild is set,
-then it indicates that this is an extended SaNameT type.
+Description
+-----------
+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.
-In this case, the value member will not contain the
-plain string. Instead it contains first a null terminated
-marker string such as "Long SaNameT..." (16 bytes long
-including the null termination).
-
-After this string there will be stored a pointer,
-which should be aligned on 64/32 bit architectures.
-That pointer is a pointer to char*, i.e. it is supposed
-to be a pointer to a null terminated string.
-
-The actual size of the string would not be stored in the length
-field. For one, it is not needed since we have a null
-terminated string. For another, it is prudent not to use the
-length field, except the high order bit, to guard against
-bugs and illegal use.
-
-This is backwards compatible in the sense that any old API
-that currently accepts SaNameT, but that has not been migrated
-to a version that understands the extended SaNameT, should
-reject the value as being too large. That is it should at least
-not just crash. The token string is also there so that naiive
-code that ignores the length field and just assumes a null
-terminated string in the old SaNameT value array, will find
-such a string. Again, it should not crash uncontrollably but
-at worst behave in a way that is not correct, but is quickly
-recognizable as to its cause.
-That "Long SaNameT..." string will be visible and recognizable
-for what it is and the bug in the old code can be fixed.
-
-Once an extended SaNameT type is supported in the the immsv,
-there is no reason to keep the 64 byte limit on RDN length.
-
+Return Values
+-------------
+A pointer to a NUL-terminated string, or a NULL pointer in case of a failure.
~~~~
---
** [tickets:#191] osaf: Extended Name Type**
**Status:** accepted
**Milestone:** 4.5.FC
**Created:** Tue May 14, 2013 08:12 AM UTC by Anders Bjornerstedt
**Last Updated:** Mon Mar 17, 2014 11:43 AM UTC
**Owner:** Anders Widell
Ticket [#643] and [#873] are for adding SaStringT-based APIs in IMM and NTF,
respectively. This ticket is for implementing a tunneling API that can be used
to tunnel NUL-terminated strings through the old SaNameT type. The tunneling
API is defined below:
Extended Name Type
==================
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.
Definition
----------
#ifdef SA_EXTENDED_NAME_SOURCE
#define SA_MAX_UNEXTENDED_NAME_LENGTH 256
#endif /* SA_EXTENDED_NAME_SOURCE */
saAisNameLend()
===============
Prototype
---------
#ifdef SA_EXTENDED_NAME_SOURCE
void
saAisNameLend(
SaConstStringT value,
SaNameT* name);
#endif /* SA_EXTENDED_NAME_SOURCE */
Parameters
----------
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.
Description
-----------
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.
saAisNameBorrow()
=================
Prototype
---------
#ifdef SA_EXTENDED_NAME_SOURCE
SaConstStringT
saAisNameBorrow(
const SaNameT* name);
#endif /* SA_EXTENDED_NAME_SOURCE */
Parameters
----------
name - [in] A pointer to an SaNameT type that has been previously set using
the saAisNameLend() function.
Description
-----------
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.
Return Values
-------------
A pointer to a NUL-terminated string, or a NULL pointer in case of a failure.
---
Sent from sourceforge.net because opensaf-tickets@lists.sourceforge.net is
subscribed to https://sourceforge.net/p/opensaf/tickets/
To unsubscribe from further messages, a project admin can change settings at
https://sourceforge.net/p/opensaf/admin/tickets/options. Or, if this is a
mailing list, you can unsubscribe from the mailing list.------------------------------------------------------------------------------
"Accelerate Dev Cycles with Automated Cross-Browser Testing - For FREE
Instantly run your Selenium tests across 300+ browser/OS combos. Get
unparalleled scalability from the best Selenium testing platform available.
Simple to use. Nothing to install. Get started now for free."
http://p.sf.net/sfu/SauceLabs
_______________________________________________
Opensaf-tickets mailing list
Opensaf-tickets@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/opensaf-tickets
