ictxRetrieveIdContext()--Retrieve Identity Context

 #include <ictx.h>;

 int ictxRetrieveIdContext
 (
  ictxStorageMech_t    *  storageMechanism,
  ictxIdContextCredential_t  *  credential,
  ictxIdContext_t     **  identityContext,
  ictxError_t          *  errorInfo
 )

The ictxRetrieveIdContext() function retrieves an identity context using the designated storage mechanism and reference to that context.

Authorities and Locks

Refer to storage mechanism for authority information. See ictxStorageMech--Identity Context Storage Mechanism Parameter.

Parameters

storageMechanism  (Input)

The storage mechanism to use when retrieving the identity context information. For the format of the structure, see ictxStorageMech--Identity Context Storage Mechanism Parameter.

credential  (Input)

The credential information that is a reference to an identity context.

identityContext  (Output)

Return pointer to the identity context that was retrieved. For the format of the structure, see ictxIdContext--Identity Context Info Parameter. When this identity context is no longer needed, it must be freed using the Free Identity Context (ictxFreeIdContext) API.

errorInfo  (Output)

The structure in which to return error code information. If the return value is not 0, errorInfo is set with additional information. This parameter may be NULL. For the format of the structure, see ictxError--Identity Context Return Code Parameter.

Return Value

The return value from the API.

0

Request was successful.

ICTXERR_PARM_REQ (1)

Missing required parameter. Please check API documentation.

ICTXERR_NOMEM (2)

No memory available. Unable to allocate required space.

ICTXERR_EIM (3)

Error occurred using EIM interfaces.

ICTXERR_STORAGEMECH_NOT_SUPPORTED (5)

The storage mechanism is not a supported storage mechanism.

ICTXERR_IDCONTEXT_NOT_FOUND (8)

Identity context was not found. The context reference may have expired or the context reference may not be usable due to clock mismatch.

ICTXERR_AMBIGUOUS (9)

Amiguous information found when searching for identity context. Unable to return identity context information.

ICTXERR_STORAGEMECH_INVALID (28)

Storage mechanism parameter is not valid. A required parameter may be missing.

eServer Implementation Notes

1. AIX implementation details:
   • Authority: None
2. Linux implementation details:
   • Authority: None
3. i5/OS implementation details:
   
   • Service Program Name: QSYS/QSYICTX
     
   • Authority: Default public authority *USE
4. Windows implementation details:
   • Authority: Users must have administrative privilege to install and work with the APIs.
5. z/OS implementation details:
   
   • Authority: The caller of the API must be APF-authorized.

Related Information

• ictxStoreIdContext() --Store Identity Context
  
  
• ictxRemoveIdContext() --Remove Identity Context
  
  
• ictxRemoveExpiredIdContexts() --Remove Expired Identity Context
  
  
• ictxFreeIdContext() --Free Identity Context Storage
  
  
• ictxFreeIdContextCredential() --Free Identity Context Credential
  
  

Example

The following example retrieves an authentication context. The caller supplies the correct storage mechanism information. Note: Read the Code example disclaimer for important legal information.

#include <ictx.h>
#include <string.h>
	

int retrieveIdContext( ictxStorageMech_t * storageMech,
		       ictxIdContextCredential_t   * credential,
                       ictxIdContext_t  ** authContext)
{
    int rc;

    ictxOptions_t options;

    ictxError_t errorInfo;

    /*----------------------------------------------------------------*/
    /*  Retrieve authentication context                               */
    /*----------------------------------------------------------------*/
    if (0 != (rc = ictxRetrieveIdContext(storageMech,
                                         credential,
                                         authContext,
                                         &errorInfo)))
    {
	.
	.
	.
        return -1;
    }
    
    return 0;
}