Sm_PolicyApi_AddRealm()

The function creates a stmndr realm within the domain that is specified in pStructRealm. The pStructRealm structure also contains other attributes of the realm, including the agent or agent group that protects the realm.
sm1252sp1
The function creates a 
CA Single Sign-On
realm within the domain that is specified in
pStructRealm
. The
pStructRealm
structure also contains other attributes of the realm, including the agent or agent group that protects the realm.
Sm_PolicyApi_AddRealm() fails if a protecting agent or agent group is not specified.
If the new realm is a top-level realm, set
pszParentRealmOid
(in Sm_PolicyApi_Realm_t) to the domain OID. Otherwise, set
pszParentRealmOid
to the OID of the new parent realm.
If the realm exists and the
bUpdate
flag is true, the existing item is updated.
The client application has the responsibility to meet the following conditions to add an authorization directory to a realm successfully:
  • The directory mapping between the authorization user directory and authentication user directory should exist.
    The Policy Management API checks only to see if the authorization user directory exists. The API does not validate a directory mapping for the given authorization user directory.
  • The associated authentication user directory should be present in the user directory collection of the domain.
Type
Realm function, domain scope.
Syntax
int SM_EXTERN Sm_PolicyApi_AddRealm (
void*pSessionHandle,Sm_PolicyApi_Realm_t*pStructRealm,const boolbUpdate
);
Parameter
I/O
Description
pSessionHandle
I
A pointer to an internal Policy Management API data structure. The structure holds information about the administrator session and the client session.
pStructRealm
I
A pointer to a completely filled-in structure.
bUpdate
I
A flag to indicate that if an existing object is found, it should be updated.
 Returns
  • Sm_PolicyApi_Success
    The realm was created successfully
  • Sm_PolicyApi_Failure
    The realm was not created successfully
  • Sm_PolicyApi_NoSession
    No valid administrator session
  • Sm_PolicyApi_InvalidHandle
    No valid initialization before this call
  • Sm_PolicyApi_NoPrivilege The administrator does not have the permission to create a realm
  • Sm_PolicyApi_InvalidOid:
    • The realm OID was not found during an update
    • The domain OID was not found
    • The agent OID or agent group OID was not found
    • The scheme OID was not found
    • The parent OID could not be found (The parent OID can be a realm OID or a domain OID.)