The direct inclusion prevention is a good idea and should be added to these files.
I think the current include file extension for the imm should be kept for now. This mainly to avoid "rocking the boat" in this area unnecessarily. Our users have a hard enough time as it is to grasp the distinction of what is available in any given imm release. Lets consolidate the include files whenever we do the next major release of OpenSaf. For SaConstStringT, one possibility is to place it in the file saImmOm_A_2_14.h for now. The IMM service will be the first to use this type in some new APIs And practically all OpenSAF users use the imm-om API in some way (even Ois). I would like not to be stuck in this include file naming discussion for too long. /AndersBj -----Original Message----- From: Anders Bjornerstedt [mailto:anders.bjornerst...@ericsson.com] Sent: den 1 april 2014 16:08 To: Anders Widell Cc: opensaf-devel@lists.sourceforge.net Subject: Re: [devel] [PATCH 1 of 1] osaf: Add definition of the new type SaConstStringT [#625] It would be possible but I am not sure it is desirable. I dont see any problem with the current names and I do see the current labeling as clear, related 1:1 to the SaVersionT setting you need to set to get access to that API version. For SaAis.h the difference is that it is not in itself any service. But I would still argue : (a) such a type would logically belong on an OpenSAF branch of the saAis.h file; and (b) it shoulod be guarded against the (yes remote) possibility that the type one day is absorbed into an offical SAF spec. Thus by placing it in an extension file that makes it clear relative to which SAF sepc this file is an extension cannot be wrong. The num2 question is here a bit of a silly problem since there exists no corresponding single service handle. In practice the nw SaConstrStringT will be used by the IMM.A.2.14 version in OpensAF4.5. Possibly the same SaConstStringT type will be used in API extenstions to other OpenSAF services produced by OpenSAF in future releases. /AndersBj Anders Widell wrote: > I think it would be possible to rename (and consolidate) the header > files for the IMM extensions, since the file names are not exposed to > the end users. The names are thus not so important - it is more of an > implementation detail. In a way, it could actually be good if the > names are a bit ugly to avoid the risk that an application programmer > by mistake includes them directly. Another thing to consider is the > risk of name collision with existing or future header files. > > Now that I think of it, we could actually do one thing to prevent > users from including the extension files directly - by adding a > preprocessor section at the top of them, e.g. like this: > > #ifndef _SA_AIS_H > #error "Don't include this file directly - include saAis.h instead" > #endif > > regards, > Anders Widell > > 2014-04-01 15:41, Mathivanan Naickan Palanivelu skrev: >> One could say the header file convention for the IMM extensions is >> already existential. >> The handle to the saAisExt.h or saAisOsafExt.h is saAis.h(when >> included), so it is not truly anonymous. At the same time, a >> convention like B_5_11 does needs some documentation of the >> convention, because i see multiple things here to digest. i.e. >> Till the tatest stable "release" (specifications release) from SAF >> which was release 6.0 or 6.1, the header files had no extensions and >> new protoptypes/APIs had a version(typically spec version) suffix. >> >> So, if we consider the "numbering" scheme, should we imagine that the >> num1 in saAis_B_<num1>_<num2>.h >> should probably indicate a futuristic release of SAF? >> AND/OR should we intend to drop the "1" (in num2) from "**_12", >> "**_13", "**_14" and say that it was really not required originally, >> but we just ended up somehow there. >> >> I agree that saAisOsafExt.h(that keeps growing as and when we update) >> is better suited to differentiate between SAF headers and the >> extended SAF headers. >> >> - Mathi. >> >> ----- anders.bjornerst...@ericsson.com wrote: >> >>> One more point is that saAisExt.h (or whatever we end up calling it) >>> should be included from saAis.h (in OpensaF 4.5). We dont want all >>> users having to figure out which new include files to explicitly >>> include to get access to extensions. It just becomes too confusing >>> and/or requires too much documentation. >>> >>> If you look at the file naming convention for the IMM API >>> extensions, there is very little risk of missundertanding that these >>> are not any regular SAF include files. >>> >>> A name like saAisExt.h feels quite anonymous and arbitrary. >>> If we are to follow that pattern I would at least prefer something >>> like saAisOsafExt.h >>> >>> /AndersBj >>> >>> -----Original Message----- >>> From: Anders Björnerstedt [mailto:anders.bjornerst...@ericsson.com] >>> Sent: den 1 april 2014 12:40 >>> To: Mathivanan Naickan Palanivelu; Anders Widell >>> Cc: opensaf-devel@lists.sourceforge.net >>> Subject: Re: [devel] [PATCH 1 of 1] osaf: Add definition of the new >>> type SaConstStringT [#625] >>> >>> Well the only issue here is the already existing pattern used for >>> the imm API extensions. >>> The significance of the B_5 suffix would be to point at the exact >>> version of that part of the SAF standard that is being extended. >>> Compare for example with saImmOm_A_2_11.h, saImmOm_A_2_12.h, >>> saImmOm_A_2_13.h And similairly for the saImmOi.h extensions. >>> >>> In this particular case, it is an addition of a completely new SAF >>> type, so I suppose the exact version of the existing SAF primitive >>> types does not matter. >>> But suppose that in a later OpenSAF release we want to extend the >>> Ais types even more. >>> Should we then just add the new types to an updated version of >>> saAisExt.h ? >>> >>> At the very least there should be a comment associated with the new >>> type that clearly states in which OpenSAF release this type was >>> added. >>> >>> /AndersBj >>> >>> >>> -----Original Message----- >>> From: Mathivanan Naickan Palanivelu >>> [mailto:mathi.naic...@oracle.com] >>> Sent: den 1 april 2014 11:59 >>> To: Anders Widell >>> Cc: opensaf-devel@lists.sourceforge.net >>> Subject: Re: [devel] [PATCH 1 of 1] osaf: Add definition of the new >>> type SaConstStringT [#625] >>> >>> Ack with the following comments: >>> >>> 1) we could name this file as saAisExt.h. >>> Please note, there is no significance for the suffix "B_5***" nor is >>> it a standard SAF convention. >>> >>> 2) The description for this file >>>> + * This file provides the suggested additions to the C language >>> binding for >>>> + * the Service Availability(TM) Forum. It contains only the >>> prototypes and >>>> + * type definitions that are part of this proposed addition. >>> These additions >>>> + * are currently NON STANDARD. But the intention is to get these >>> additions >>>> + * approved formally by SAF in the future. >>> Could be changed to something like: >>> >>> "This file defines extensions to the C header files provided by the >>> Service Availability(TM) Forum AIS specifications. >>> It contains extended prototypes and type definitions. The intention >>> is to get these additions Included as a part of SAF standard >>> specifications." >>> >>> Thanks, >>> Mathi. >>> >>> >>> >>>> -----Original Message----- >>>> From: Anders Widell [mailto:anders.wid...@ericsson.com] >>>> Sent: Friday, March 07, 2014 7:29 PM >>>> To: Mathivanan Naickan Palanivelu >>>> Cc: opensaf-devel@lists.sourceforge.net >>>> Subject: [PATCH 1 of 1] osaf: Add definition of the new type >>>> SaConstStringT [#625] >>>> >>>> osaf/libs/saf/include/Makefile.am | 1 + >>>> osaf/libs/saf/include/saAis.h | 2 + >>>> osaf/libs/saf/include/saAis_B_5_14.h | 39 >>>> ++++++++++++++++++++++++++++++++++++ >>>> 3 files changed, 42 insertions(+), 0 deletions(-) >>>> >>>> >>>> Add a definition of SaConstStringT as an OpenSAF extension to the >>>> AIS >>> types. >>>> The following example code illustrates a use case where >>> SaConstStringT >>>> is >>>> needed: >>>> >>>> void foo(SaConstStringT s) { >>>> printf("%s", s); >>>> } >>>> >>>> void bar(const char* s) { >>>> foo(s); >>>> } >>>> >>>> By using SaConstStringT instead of SaStringT (or const SaStringT), >>>> we avoid having to cast way the const qualifier of the string when >>> calling >>>> foo() from bar(). >>>> >>>> diff --git a/osaf/libs/saf/include/Makefile.am >>>> b/osaf/libs/saf/include/Makefile.am >>>> --- a/osaf/libs/saf/include/Makefile.am >>>> +++ b/osaf/libs/saf/include/Makefile.am >>>> @@ -20,6 +20,7 @@ MAINTAINERCLEANFILES = Makefile.in >>>> >>>> include_HEADERS = \ >>>> saAis.h \ >>>> + saAis_B_5_14.h \ >>>> saAmf.h \ >>>> saCkpt.h \ >>>> saCkpt_B_02_03.h \ >>>> diff --git a/osaf/libs/saf/include/saAis.h >>>> b/osaf/libs/saf/include/saAis.h >>>> --- a/osaf/libs/saf/include/saAis.h >>>> +++ b/osaf/libs/saf/include/saAis.h >>>> @@ -179,5 +179,7 @@ typedef union { } #endif >>>> >>>> +#include <saAis_B_5_14.h> >>>> + >>>> #endif /* _SA_AIS_H */ >>>> >>>> diff --git a/osaf/libs/saf/include/saAis_B_5_14.h >>>> b/osaf/libs/saf/include/saAis_B_5_14.h >>>> new file mode 100644 >>>> --- /dev/null >>>> +++ b/osaf/libs/saf/include/saAis_B_5_14.h >>>> @@ -0,0 +1,39 @@ >>>> +/* -*- OpenSAF -*- >>>> + * >>>> + * (C) Copyright 2014 The OpenSAF Foundation >>>> + * >>>> + * This program is distributed in the hope that it will be useful, >>> but >>>> + * WITHOUT ANY WARRANTY; without even the implied warranty of >>>> MERCHANTABILITY >>>> + * or FITNESS FOR A PARTICULAR PURPOSE. This file and program are >>>> licensed >>>> + * under the GNU Lesser General Public License Version 2.1, >>>> + February >>> 1999. >>>> + * The complete license can be accessed from the following >>> location: >>>> + * http://opensource.org/licenses/lgpl-license.php >>>> + * See the Copying file included with the OpenSAF distribution for >>>> + full >>>> + * licensing terms. >>>> + * >>>> + * Author(s): Ericsson AB >>>> + */ >>>> + >>>> +/* >>>> + * DESCRIPTION: >>>> + * This file provides the suggested additions to the C language >>> binding for >>>> + * the Service Availability(TM) Forum. It contains only the >>> prototypes and >>>> + * type definitions that are part of this proposed addition. >>> These additions >>>> + * are currently NON STANDARD. But the intention is to get these >>> additions >>>> + * approved formally by SAF in the future. >>>> + */ >>>> + >>>> +#ifndef _SA_AIS_B_5_14_H >>>> +#define _SA_AIS_B_5_14_H >>>> + >>>> +#ifdef __cplusplus >>>> +extern "C" { >>>> +#endif >>>> + >>>> +typedef const char* SaConstStringT; >>>> + >>>> +#ifdef __cplusplus >>>> +} >>>> +#endif >>>> + >>>> +#endif /* _SA_AIS_B_5_14_H */ >>> -------------------------------------------------------------------- >>> ---------- >>> >>> _______________________________________________ >>> Opensaf-devel mailing list >>> Opensaf-devel@lists.sourceforge.net >>> https://lists.sourceforge.net/lists/listinfo/opensaf-devel >>> >>> -------------------------------------------------------------------- >>> ---------- >>> >>> _______________________________________________ >>> Opensaf-devel mailing list >>> Opensaf-devel@lists.sourceforge.net >>> https://lists.sourceforge.net/lists/listinfo/opensaf-devel > > ------------------------------------------------------------------------------ _______________________________________________ Opensaf-devel mailing list Opensaf-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/opensaf-devel ------------------------------------------------------------------------------ _______________________________________________ Opensaf-devel mailing list Opensaf-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/opensaf-devel
