Will fix the typos before pushing. /AndersBj
On 03/25/2015 02:43 PM, Zoran Milinkovic wrote: > Hi, > > Find my comments inline. > > -----Original Message----- > From: Anders Bjornerstedt [mailto:anders.bjornerst...@ericsson.com] > Sent: Wednesday, March 25, 2015 6:17 AM > To: reddy.neelaka...@oracle.com > Cc: opensaf-devel@lists.sourceforge.net > Subject: [devel] [PATCH 1 of 1] IMM: Add immsv/README.SASTRINGT_API > documenting a new API added in 4.6 [#1256] > > osaf/services/saf/immsv/README.SASTRINGT_API | 265 > +++++++++++++++++++++++++++ > 1 files changed, 265 insertions(+), 0 deletions(-) > > > diff --git a/osaf/services/saf/immsv/README.SASTRINGT_API > b/osaf/services/saf/immsv/README.SASTRINGT_API > new file mode 100644 > --- /dev/null > +++ b/osaf/services/saf/immsv/README.SASTRINGT_API > @@ -0,0 +1,265 @@ > +IMM API that replaces SaNameT with SaStringT and SA_IMM_ATTR_DN > +=============================================================== > +http://sourceforge.net/p/opensaf/tickets/643 > +This enhancement provides an updated API where all use of the > +troublesome SaNameT type is replaced by the SaStringT type or the > SaConstStringT type (#625). > +Also added is a new flag value for attribute definitions: SA_IMM_ATTR_DN. > + > +Defining an attribute in an IMM class definition on the SaStringT type > +and also setting the flag SA_IMM_ATTR_DN, will mean that the attribute > +is intended to hold a value that should be a DN. > + > +Other flags that make sense to also set on in combination with > +SA_IMM_ATTR_DN when applicable are: > + > +SA_IMM_ATTR_RDN if this is the RDN attribute. Just as having SaNameT > +the type of an RDN attribute indicates that the class is an association > +class, having SaStringT and SA_IMM_ATTR_DN combined with > +SA_IMM_ATTR_RDN would also indicate that this is an association class. > + > +SA_IMM_ATTR_NO_DANGLING. Previously (OpenSAF 4.5) was only allowed on > +attributes of type SaNameT, but will in Opensaf 4.6 also be allowed on > +attributes of type SaStringT if the SA_IMM_ATTR_DN flag is also set. > +The exception is the RDN attribute which still can not have the > +SA_IMM_ATTR_NO_DANGLING set. > + > +All the other flags may also be used in combination with > +SA_IMM_ATTR_DN, with the normal meaning. > > [Zoran] SA_IMM_ATTR_DN can only be used with SaStringT type. Other > combinations are not allowed. > > + > +The SaStringT API provides the same functions as the SaNameT based API > +with almost the same semantics as the A.2.X spec. Where there is a > difference this is commented below. > +-------- > + > + /* 4.5.1 saImmOmSearchInitialize() */ > + extern SaAisErrorT > + saImmOmSearchInitialize_o3(SaImmHandleT immHandle, > + SaConstStringT rootName, > + SaImmScopeT scope, > + SaImmSearchOptionsT searchOptions, > + const SaImmSearchParametersT_2 *searchParam, > + const SaImmAttrNameT *attributeNames, > SaImmSearchHandleT > +*searchHandle); > + > + /* 4.5.2 saImmOmSearchNext() */ > + extern SaAisErrorT > + saImmOmSearchNext_o3(SaImmSearchHandleT searchHandle, SaStringT > +*objectName, SaImmAttrValuesT_2 ***attributes); > + > +The RDN attribute is by default not returned by saImmOmSearchNext_o3. > +Only if saImmOmSearchInitialize_o3 sets SA_IMM_SEARCH_GET_SOME_ATTR > +option in the searchOptions parameter and explicitly includes the RDN > attribute in the attributeNames parameter, will the RDN attribute be returned. > +There should never be any need to fetch the RDN attribute with the new > +API since the create APIs (OM and OI, downcalls and callbacks) have been > simplified to use the objectDN instead of the parentDN and RDN attribute. > +The RDN is a also redundant copy of part of the DN and can be extracted > [Zoran] typo 'is A also' > > +from the DN, which is returned by saImmOmSearchNext_o3. > +--------- > + > + /* 4.6.2 saImmOmAccessorGet() */ > + extern SaAisErrorT > + saImmOmAccessorGet_o3(SaImmAccessorHandleT accessorHandle, > + SaConstStringT objectName, > + const SaImmAttrNameT *attributeNames, > SaImmAttrValuesT_2 > +***attributes); > + > +The RDN attribute is by default not returned by saImmOmAccessorGet_o3. > +Only if the attributeNames parameter explicitly includes the RDN attribute, > will the RDN attribute be returned. > +There should never be any need to fetch the RDN attribute with the new > +API since the create APIs (OM and OI, downcalls and callbacks) have been > simplified to use the objectDN instead of the parentDN and RDN attribute. > +The RDN is a also redundant copy of part of the DN and can be extracted from > the DN, which is input to this PI. > [Zoran] typo 'is A also' > > +---------- > + > + /* 4.7.2 saImmOmAdminOwnerSet() */ > + > + extern SaAisErrorT > + saImmOmAdminOwnerSet_o3(SaImmAdminOwnerHandleT ownerHandle, > +SaConstStringT *objectNames, SaImmScopeT scope); > +---------- > + > + /* 4.7.3 saImmOmAdminOwnerRelease() */ > + > + extern SaAisErrorT > + saImmOmAdminOwnerRelease_o3(SaImmAdminOwnerHandleT ownerHandle, > +SaConstStringT *objectNames, SaImmScopeT scope); > +---------- > + > + /* 4.7.5 saImmOmAdminOwnerClear() */ > + > + extern SaAisErrorT > + saImmOmAdminOwnerClear_o3(SaImmHandleT immHandle, SaConstStringT > +*objectNames, SaImmScopeT scope); > +---------- > + > + /* 4.8.2 saImmOmCcbObjectCreate() */ > + extern SaAisErrorT > + saImmOmCcbObjectCreate_o3(SaImmCcbHandleT ccbHandle, > + const SaImmClassNameT className, > + SaConstStringT objectName, const > SaImmAttrValuesT_2 > +**attrValues); > + > +Note that instead of "parentName" the saImmOmCcbObjectCreate_o3 API > +takes the DN for the object proposed for create in the parameter > +"objectName". The RDN attribute is not allowed to be in the attrValues list > since it is redundant and indicates the user has misunderstood this new API. > +--------- > + > + /* 4.8.3 saImmOmCcbObjectDelete() */ > + > + extern SaAisErrorT > + saImmOmCcbObjectDelete_o3(SaImmCcbHandleT ccbHandle, SaConstStringT > +objectName); > +--------- > + > + /* 4.8.4 saImmOmCcbObjectModify() */ > + extern SaAisErrorT > + saImmOmCcbObjectModify_o3(SaImmCcbHandleT ccbHandle, > + SaConstStringT objectName, const > SaImmAttrModificationT_2 > +**attrMods); > +--------- > + > + /* 4.9.1 saImmOmAdminOperationInvoke(), > + saImmOmAdminOperationInvokeAsync() > + */ > + extern SaAisErrorT > + saImmOmAdminOperationInvoke_o3( > + SaImmAdminOwnerHandleT ownerHandle, > + SaConstStringT objectName, > + SaImmContinuationIdT continuationId, > + SaImmAdminOperationIdT operationId, > + const SaImmAdminOperationParamsT_2 > **params, > + SaAisErrorT *operationReturnValue, > + SaTimeT timeout, > + SaImmAdminOperationParamsT_2 > ***returnParams); > +--------- > + > + extern SaAisErrorT > + saImmOmAdminOperationInvokeAsync_o3(SaImmAdminOwnerHandleT ownerHandle, > + SaInvocationT invocation, > + SaConstStringT objectName, > + SaImmContinuationIdT > continuationId, > + SaImmAdminOperationIdT operationId, > + const SaImmAdminOperationParamsT_2 > **params); > +--------- > + > + /* This API is not implemented in OpenSAF, but the SaStringT API > +variant is defined for completenes. */ > + > + extern SaAisErrorT > + saImmOmAdminOperationContinue_o3( > + SaImmAdminOwnerHandleT ownerHandle, > + SaConstStringT objectName, > + SaImmContinuationIdT continuationId, > + SaAisErrorT *operationReturnValue, > + SaImmAdminOperationParamsT_2 > ***returnParams); > +--------- > + > + /* This API is not implemented in OpenSAF, but the SaStringT API > +variant is defined for completenes. */ > + > + extern SaAisErrorT > + saImmOmAdminOperationContinueAsync_o3(SaImmAdminOwnerHandleT > ownerHandle, > + SaInvocationT invocation, > + SaConstStringT objectName, > SaImmContinuationIdT > +continuationId); > + > +--------- > + /* This API is not implemented in OpenSAF, but the SaStringT API > +variant is defined for completenes. */ > + > + extern SaAisErrorT > + saImmOmAdminOperationContinuationClear_o3(SaImmAdminOwnerHandleT > ownerHandle, > + SaConstStringT objectName, > SaImmContinuationIdT > +continuationId); > +--------- > + > + /* 4.2.5 SaImmAttrFlagsT */ > + > +#define SA_IMM_ATTR_DN 0x0000000008000000 > + > +This flag is only allowed on attributes of type SA_IMM_ATTR_SASTRINGT and > then indicates that the value is a DN. > +-------- > + > + /* From 5.5.4 */ > + typedef SaAisErrorT > + (*SaImmOiRtAttrUpdateCallbackT_o3) (SaImmOiHandleT immOiHandle, > + SaConstStringT objectName, const > SaImmAttrNameT > +*attributeNames); > +-------- > + > + /* From 5.6.1 */ > + typedef SaAisErrorT > + (*SaImmOiCcbObjectCreateCallbackT_o3) (SaImmOiHandleT immOiHandle, > + SaImmOiCcbIdT ccbId, > + const SaImmClassNameT className, > + SaConstStringT objectName, const > SaImmAttrValuesT_2 > +**attr); > + > +Note that instead of "parentName" the > +SaImmOiCcbObjectCreateCallbackT_o3 provides the DN for the object > +proposed for create in the parameter "objectName". The RDN attribute is not > included in the attrValues list since it is redundant and no longer needed by > the OI for construvting the DN. > [Zoran] typo 'construvting' > > Best regards, > Zoran > > +-------- > + > + /* From 5.6.2 */ > + typedef SaAisErrorT > + (*SaImmOiCcbObjectDeleteCallbackT_o3) (SaImmOiHandleT immOiHandle, > + SaImmOiCcbIdT ccbId, > SaConstStringT objectName); > +-------- > + > + /* From 5.6.3 */ > + typedef SaAisErrorT > + (*SaImmOiCcbObjectModifyCallbackT_o3) (SaImmOiHandleT immOiHandle, > + SaImmOiCcbIdT ccbId, > + SaConstStringT objectName, const > SaImmAttrModificationT_2 > +**attrMods); > +-------- > + > + /* From 5.7.1 */ > + typedef void > + (*SaImmOiAdminOperationCallbackT_o3) (SaImmOiHandleT immOiHandle, > + SaInvocationT invocation, > + SaConstStringT objectName, > + SaImmAdminOperationIdT > operationId, > + const > SaImmAdminOperationParamsT_2 **params); > +-------- > + > + /* SaImmOiCallbacksT_2 */ > + typedef struct { > + SaImmOiAdminOperationCallbackT_o3 saImmOiAdminOperationCallback; > + SaImmOiCcbAbortCallbackT saImmOiCcbAbortCallback; > + SaImmOiCcbApplyCallbackT saImmOiCcbApplyCallback; > + SaImmOiCcbCompletedCallbackT saImmOiCcbCompletedCallback; > + SaImmOiCcbObjectCreateCallbackT_o3 > saImmOiCcbObjectCreateCallback; > + SaImmOiCcbObjectDeleteCallbackT_o3 > saImmOiCcbObjectDeleteCallback; > + SaImmOiCcbObjectModifyCallbackT_o3 > saImmOiCcbObjectModifyCallback; > + SaImmOiRtAttrUpdateCallbackT_o3 saImmOiRtAttrUpdateCallback; > + } SaImmOiCallbacksT_o3; > +-------- > + > + /* 5.3.1 saImmOiInitialize() */ > + extern SaAisErrorT > + saImmOiInitialize_o3(SaImmOiHandleT *immOiHandle, > + const SaImmOiCallbacksT_o3 *immOiCallbacks, > SaVersionT > +*version); > +-------- > + > + /* 5.4.6 saImmOiObjectImplementerSet() */ > + extern SaAisErrorT > + saImmOiObjectImplementerSet_o3(SaImmOiHandleT immOiHandle, > +SaConstStringT objectName, SaImmScopeT scope); > +-------- > + > + /* 5.4.6 saImmOiObjectImplementerRelease() */ > + > + extern SaAisErrorT > + saImmOiObjectImplementerRelease_o3(SaImmOiHandleT immOiHandle, > +SaConstStringT objectName, SaImmScopeT scope); > +-------- > + > + /* > + * > + * Runtime Object Management Routines > + * > + */ > + > + /* 5.5.1 saImmOiRtObjectCreate() */ > + > + extern SaAisErrorT > + saImmOiRtObjectCreate_o3(SaImmOiHandleT immOiHandle, > + const SaImmClassNameT className, > + SaConstStringT objectName, const > SaImmAttrValuesT_2 **attrValues); > + > +Note that instead of "parentName" the saImmOiRtObjectCreate_o3 API > +takes the DN for the object proposed for create in the parameter > +"objectName". The RDN attribute is not allowed to be in the attrValues list > since it is redundant and indicates the user has misunderstood this new API. > +-------- > + > + /* 5.5.2 saImmOiRtObjectDelete() */ > + > + extern SaAisErrorT > + saImmOiRtObjectDelete_o3(SaImmOiHandleT immOiHandle, SaConstStringT > +objectName); > +-------- > + > + /* 5.5.3 saImmOiRtObjectUpdate() */ > + > + extern SaAisErrorT > + saImmOiRtObjectUpdate_o3(SaImmOiHandleT immOiHandle, > + SaConstStringT objectName, const > SaImmAttrModificationT_2 > +**attrMods); > + > > ------------------------------------------------------------------------------ > Dive into the World of Parallel Programming The Go Parallel Website, > sponsored by Intel and developed in partnership with Slashdot Media, is your > hub for all things parallel software development, from weekly thought > leadership blogs to news, videos, case studies, tutorials and more. Take a > look and join the conversation now. http://goparallel.sourceforge.net/ > _______________________________________________ > Opensaf-devel mailing list > Opensaf-devel@lists.sourceforge.net > https://lists.sourceforge.net/lists/listinfo/opensaf-devel ------------------------------------------------------------------------------ Dive into the World of Parallel Programming The Go Parallel Website, sponsored by Intel and developed in partnership with Slashdot Media, is your hub for all things parallel software development, from weekly thought leadership blogs to news, videos, case studies, tutorials and more. Take a look and join the conversation now. http://goparallel.sourceforge.net/ _______________________________________________ Opensaf-devel mailing list Opensaf-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/opensaf-devel
