"Fossies" - the Fresh Open Source Software Archive

Member "opensaf-5.21.09/src/imm/README.SASTRINGT_API" (31 May 2021, 10706 Bytes) of package /linux/misc/opensaf-5.21.09.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file.

    1 IMM API that replaces SaNameT with SaStringT and SA_IMM_ATTR_DN
    2 ===============================================================
    3 http://sourceforge.net/p/opensaf/tickets/643
    4 This enhancement provides an updated API where all use of the troublesome
    5 SaNameT type is replaced by the SaStringT type or the SaConstStringT type (#625).
    6 Also added is a new flag value for attribute definitions: SA_IMM_ATTR_DN.
    7 
    8 The new APIs all have the suffix _o3.
    9 The *_o3 APIS are only available when IMM OI/OM registers with version A.02.15.
   10 
   11 Defining an attribute in an IMM class definition on the SaStringT type and
   12 also setting the flag SA_IMM_ATTR_DN, will mean that the attribute is intended
   13 to hold a value that should be a DN.
   14 
   15 Other SaImmAttrFlagsT values that also make sense to set in combination with
   16 SA_IMM_ATTR_DN when applicable are:
   17 
   18 SA_IMM_ATTR_RDN if this is the RDN attribute. Just as having SaNameT the 
   19 type of an RDN attribute indicates that the class is an association class,
   20 having SaStringT and SA_IMM_ATTR_DN combined with SA_IMM_ATTR_RDN would 
   21 also indicate that this is an association class.
   22 
   23 SA_IMM_ATTR_NO_DANGLING. Previously (OpenSAF 4.5) was only allowed 
   24 on attributes of type SaNameT, but will in Opensaf 4.6 also be allowed on
   25 attributes of type SaStringT if the SA_IMM_ATTR_DN flag is also set.
   26 The exception is the RDN attribute which still can not have the 
   27 SA_IMM_ATTR_NO_DANGLING set. 
   28 
   29 All the other SaImmAttrFlagsT values may also be used in combination with
   30 SA_IMM_ATTR_DN, with the normal meaning. But the only attribute *type* that
   31 can be combined with SA_IMM_ATTR_DN flag is the type SA_IMM_ATTR_SASTRINGT.
   32 
   33 The SaStringT API provides the same functions as the SaNameT based API with
   34 almost the same semantics as the A.2.X spec. Where there is a difference this
   35 is commented below.
   36 --------
   37 
   38     /* 4.5.1 saImmOmSearchInitialize() */
   39     extern SaAisErrorT
   40      saImmOmSearchInitialize_o3(SaImmHandleT immHandle,
   41                     SaConstStringT rootName,
   42                     SaImmScopeT scope,
   43                     SaImmSearchOptionsT searchOptions,
   44                     const SaImmSearchParametersT_2 *searchParam, 
   45                     const SaImmAttrNameT *attributeNames, SaImmSearchHandleT *searchHandle);
   46 
   47     /* 4.5.2 saImmOmSearchNext() */
   48     extern SaAisErrorT
   49      saImmOmSearchNext_o3(SaImmSearchHandleT searchHandle, SaStringT *objectName, SaImmAttrValuesT_2 ***attributes);
   50 
   51 The RDN attribute is by default not returned by saImmOmSearchNext_o3.
   52 Only if saImmOmSearchInitialize_o3 sets SA_IMM_SEARCH_GET_SOME_ATTR option in the searchOptions parameter and
   53 explicitly includes the RDN attribute in the attributeNames parameter, will the RDN attribute be returned.
   54 There should never be any need to fetch the RDN attribute with the new API since the create APIs (OM and OI, 
   55 downcalls and callbacks) have been simplified to use the objectDN instead of the parentDN and RDN attribute.
   56 The RDN is also redundant copy of part of the DN and can be extracted from the DN, which is returned by
   57 saImmOmSearchNext_o3.
   58 ---------
   59 
   60     /* 4.6.2 saImmOmAccessorGet() */
   61     extern SaAisErrorT
   62      saImmOmAccessorGet_o3(SaImmAccessorHandleT accessorHandle,
   63                    SaConstStringT objectName,
   64                    const SaImmAttrNameT *attributeNames, SaImmAttrValuesT_2 ***attributes);
   65 
   66 The RDN attribute is by default not returned by saImmOmAccessorGet_o3.
   67 Only if the attributeNames parameter explicitly includes the RDN attribute, will the RDN attribute be returned.
   68 There should never be any need to fetch the RDN attribute with the new API since the create APIs (OM and OI, 
   69 downcalls and callbacks) have been simplified to use the objectDN instead of the parentDN and RDN attribute.
   70 The RDN is also redundant copy of part of the DN and can be extracted from the DN, which is input to this PI.
   71 ----------
   72 
   73     /* 4.7.2 saImmOmAdminOwnerSet() */
   74 
   75     extern SaAisErrorT
   76      saImmOmAdminOwnerSet_o3(SaImmAdminOwnerHandleT ownerHandle, SaConstStringT *objectNames, SaImmScopeT scope);
   77 ----------
   78 
   79     /* 4.7.3 saImmOmAdminOwnerRelease() */
   80 
   81     extern SaAisErrorT
   82      saImmOmAdminOwnerRelease_o3(SaImmAdminOwnerHandleT ownerHandle, SaConstStringT *objectNames, SaImmScopeT scope);
   83 ----------
   84 
   85     /* 4.7.5 saImmOmAdminOwnerClear() */
   86 
   87     extern SaAisErrorT
   88      saImmOmAdminOwnerClear_o3(SaImmHandleT immHandle, SaConstStringT *objectNames, SaImmScopeT scope);
   89 ----------
   90 
   91     /* 4.8.2 saImmOmCcbObjectCreate() */
   92     extern SaAisErrorT
   93      saImmOmCcbObjectCreate_o3(SaImmCcbHandleT ccbHandle,
   94                    const SaImmClassNameT className,
   95                    SaConstStringT objectName, const SaImmAttrValuesT_2 **attrValues);
   96 
   97 Note that instead of "parentName" the saImmOmCcbObjectCreate_o3 API takes the DN for the object proposed for create
   98 in the parameter "objectName". The RDN  attribute is not allowed to be in the attrValues list since it is redundant
   99 and indicates the user has misunderstood this new API.
  100 ---------
  101 
  102     /* 4.8.3 saImmOmCcbObjectDelete() */
  103 
  104     extern SaAisErrorT
  105      saImmOmCcbObjectDelete_o3(SaImmCcbHandleT ccbHandle, SaConstStringT objectName);
  106 ---------
  107 
  108     /* 4.8.4 saImmOmCcbObjectModify() */
  109     extern SaAisErrorT
  110      saImmOmCcbObjectModify_o3(SaImmCcbHandleT ccbHandle,
  111                    SaConstStringT objectName, const SaImmAttrModificationT_2 **attrMods);
  112 ---------
  113 
  114     /* 4.9.1 saImmOmAdminOperationInvoke(),
  115        saImmOmAdminOperationInvokeAsync() 
  116     */
  117     extern SaAisErrorT
  118      saImmOmAdminOperationInvoke_o3(
  119                      SaImmAdminOwnerHandleT ownerHandle,
  120                      SaConstStringT objectName,
  121                      SaImmContinuationIdT continuationId,
  122                      SaImmAdminOperationIdT operationId,
  123                      const SaImmAdminOperationParamsT_2 **params,
  124                      SaAisErrorT *operationReturnValue,
  125                      SaTimeT timeout,
  126                      SaImmAdminOperationParamsT_2 ***returnParams);
  127 ---------
  128 
  129     extern SaAisErrorT
  130      saImmOmAdminOperationInvokeAsync_o3(SaImmAdminOwnerHandleT ownerHandle,
  131                          SaInvocationT invocation,
  132                          SaConstStringT objectName,
  133                          SaImmContinuationIdT continuationId,
  134                          SaImmAdminOperationIdT operationId,
  135                          const SaImmAdminOperationParamsT_2 **params);
  136 ---------
  137 
  138     /* This API is not implemented in OpenSAF, but the SaStringT API variant is defined for completenes. */
  139 
  140     extern SaAisErrorT
  141      saImmOmAdminOperationContinue_o3(
  142                         SaImmAdminOwnerHandleT ownerHandle,
  143                         SaConstStringT objectName,
  144                         SaImmContinuationIdT continuationId,
  145                         SaAisErrorT *operationReturnValue,
  146                         SaImmAdminOperationParamsT_2 ***returnParams);
  147 ---------
  148 
  149     /* This API is not implemented in OpenSAF, but the SaStringT API variant is defined for completenes. */
  150 
  151     extern SaAisErrorT
  152      saImmOmAdminOperationContinueAsync_o3(SaImmAdminOwnerHandleT ownerHandle,
  153                            SaInvocationT invocation,
  154                            SaConstStringT objectName, SaImmContinuationIdT continuationId);
  155 
  156 ---------
  157     /* This API is not implemented in OpenSAF, but the SaStringT API variant is defined for completenes. */
  158 
  159     extern SaAisErrorT
  160      saImmOmAdminOperationContinuationClear_o3(SaImmAdminOwnerHandleT ownerHandle,
  161                            SaConstStringT objectName, SaImmContinuationIdT continuationId);
  162 ---------
  163 
  164     /* 4.2.5 SaImmAttrFlagsT */
  165 
  166 #define SA_IMM_ATTR_DN            0x0000000008000000
  167 
  168 This flag is only allowed on attributes of type SA_IMM_ATTR_SASTRINGT and then indicates that the value is a DN.
  169 --------
  170 
  171     /* From 5.5.4  */
  172     typedef SaAisErrorT
  173      (*SaImmOiRtAttrUpdateCallbackT_o3) (SaImmOiHandleT immOiHandle,
  174                       SaConstStringT objectName, const SaImmAttrNameT *attributeNames);
  175 --------
  176 
  177     /* From 5.6.1 */
  178     typedef SaAisErrorT
  179      (*SaImmOiCcbObjectCreateCallbackT_o3) (SaImmOiHandleT immOiHandle,
  180                            SaImmOiCcbIdT ccbId,
  181                            const SaImmClassNameT className,
  182                            SaConstStringT objectName, const SaImmAttrValuesT_2 **attr);
  183 
  184 Note that instead of "parentName" the SaImmOiCcbObjectCreateCallbackT_o3 provides the DN for the object proposed for create
  185 in the parameter "objectName". The RDN  attribute is not included in the attrValues list since it is redundant and no longer
  186 needed by the OI for constructing the DN. 
  187 --------
  188 
  189     /* From 5.6.2  */
  190     typedef SaAisErrorT
  191      (*SaImmOiCcbObjectDeleteCallbackT_o3) (SaImmOiHandleT immOiHandle,
  192                          SaImmOiCcbIdT ccbId, SaConstStringT objectName);
  193 --------
  194 
  195     /* From 5.6.3  */
  196     typedef SaAisErrorT
  197      (*SaImmOiCcbObjectModifyCallbackT_o3) (SaImmOiHandleT immOiHandle,
  198                            SaImmOiCcbIdT ccbId,
  199                            SaConstStringT objectName, const SaImmAttrModificationT_2 **attrMods);
  200 --------
  201 
  202     /* From 5.7.1  */
  203     typedef void
  204      (*SaImmOiAdminOperationCallbackT_o3) (SaImmOiHandleT immOiHandle,
  205                           SaInvocationT invocation,
  206                           SaConstStringT objectName,
  207                           SaImmAdminOperationIdT operationId,
  208                           const SaImmAdminOperationParamsT_2 **params);
  209 --------
  210 
  211     /* SaImmOiCallbacksT_2 */
  212     typedef struct {
  213         SaImmOiAdminOperationCallbackT_o3 saImmOiAdminOperationCallback;
  214         SaImmOiCcbAbortCallbackT saImmOiCcbAbortCallback;
  215         SaImmOiCcbApplyCallbackT saImmOiCcbApplyCallback;
  216         SaImmOiCcbCompletedCallbackT saImmOiCcbCompletedCallback;
  217         SaImmOiCcbObjectCreateCallbackT_o3 saImmOiCcbObjectCreateCallback;
  218         SaImmOiCcbObjectDeleteCallbackT_o3 saImmOiCcbObjectDeleteCallback;
  219         SaImmOiCcbObjectModifyCallbackT_o3 saImmOiCcbObjectModifyCallback;
  220         SaImmOiRtAttrUpdateCallbackT_o3 saImmOiRtAttrUpdateCallback;
  221     } SaImmOiCallbacksT_o3;
  222 --------
  223 
  224     /* 5.3.1 saImmOiInitialize() */
  225     extern SaAisErrorT
  226      saImmOiInitialize_o3(SaImmOiHandleT *immOiHandle,
  227                  const SaImmOiCallbacksT_o3 *immOiCallbacks, SaVersionT *version);
  228 --------
  229 
  230     /* 5.4.6 saImmOiObjectImplementerSet() */
  231     extern SaAisErrorT
  232      saImmOiObjectImplementerSet_o3(SaImmOiHandleT immOiHandle, SaConstStringT objectName, SaImmScopeT scope);
  233 --------
  234 
  235     /* 5.4.6 saImmOiObjectImplementerRelease() */
  236 
  237     extern SaAisErrorT
  238      saImmOiObjectImplementerRelease_o3(SaImmOiHandleT immOiHandle, SaConstStringT objectName, SaImmScopeT scope);
  239 --------
  240 
  241     /*
  242      *
  243      * Runtime Object Management Routines
  244      *
  245      */
  246 
  247     /* 5.5.1 saImmOiRtObjectCreate() */
  248 
  249     extern SaAisErrorT
  250      saImmOiRtObjectCreate_o3(SaImmOiHandleT immOiHandle,
  251                  const SaImmClassNameT className,
  252                  SaConstStringT objectName, const SaImmAttrValuesT_2 **attrValues);
  253 
  254 Note that instead of "parentName" the saImmOiRtObjectCreate_o3 API takes the DN for the object proposed for create
  255 in the parameter "objectName". The RDN  attribute is not allowed to be in the attrValues list since it is redundant
  256 and indicates the user has misunderstood this new API.
  257 --------
  258 
  259     /* 5.5.2 saImmOiRtObjectDelete() */
  260 
  261     extern SaAisErrorT
  262      saImmOiRtObjectDelete_o3(SaImmOiHandleT immOiHandle, SaConstStringT objectName);
  263 --------
  264 
  265     /* 5.5.3 saImmOiRtObjectUpdate() */
  266 
  267     extern SaAisErrorT
  268      saImmOiRtObjectUpdate_o3(SaImmOiHandleT immOiHandle,
  269                  SaConstStringT objectName, const SaImmAttrModificationT_2 **attrMods);
  270