Programming Guides › Programming Guide for C › Policy Management API › Function Declarations for the Policy Management API › Sm_PolicyApi_AddRealm()

Sm_PolicyApi_AddRealm()

Creates a new SiteMinder realm within the domain 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 realm's parent realm.

If the realm exists and the bUpdate flag is true, the existing item is updated.

It is the responsibility of the client application to meet the following conditions in order to add an authorization directory to a realm successfully:

• The directory mapping between the authorization user directory and authentication user directory should exist.

  Note: The Policy Management API checks only to see if the authorization user directory exists. It does not validate if there is 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 bool               bUpdate
);

Returns

• Sm_PolicyApi_Success. The realm was created successfully.
• Sm_PolicyApi_Failure. The realm was not created successfully.
• Sm_PolicyApi_NoSession. There is no valid administrator session.
• Sm_PolicyApi_InvalidHandle. There was no valid initialization prior to this call.
• Sm_PolicyApi_NoPrivilege. The administrator does not have the privilege 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.)