We had a discussion regarding this in TLC and the conclusion was that we go for the originally proposed file name saAis_B_5_14.h for now so that it is consistent with the names other existing header files, and then at a later point we can revisit this issue and rename/consolidate the file names for all services at once.
regards, Anders Widell 2014-04-02 09:52, Anders Björnerstedt skrev: > 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
