NAME

CSSM_KR_RecoveryRetrieve

SYNOPSIS

CSSM_RETURN CSSMAPI CSSM_KR_RecoveryRetrieve
    (CSSM_KR_HANDLE KRSPHandle,
    CSSM_HANDLE ReferenceHandle,
    uint32 *EstimatedTime,
    CSSM_HANDLE_PTR CacheHandle,
    uint32 *NumberOfRecoveredKeys)

DESCRIPTION

This function completes a key recovery request operation. The ReferenceHandle parameter indicates which outstanding recovery request is to be completed. The results of a successful recovery operation are referenced by the ResultsHandle parameter, which may be used with the CSSM_KR_GetRecoveredObject function to retrieve the recovered keys.

If the results are not available at the time this function is invoked, the CacheHandle is NULL, and the EstimatedTime parameter indicates when this operation should be repeated with the same ReferenceHandle.

PARAMETERS

KRSPHandle (input)

The handle of the KR module to perform this operation.

ReferenceHandle (input)

A reference handle which uniquely identifies the CSSM_KR_RecoveryRequest call that initiated recovery of the set of keys returned by this function.

EstimatedTime (output)

The number of seconds estimated before the set of recovered keys will be returned. A (default) value of zero indicates that the set has been returned as a result of this call.

CacheHandle (output)

A reference handle which uniquely identifies the cache of recovered keys. If the object retrieval process has not been completed, the returned cache handle is NULL. A non-NULL cache handle can be used in the CSSM_KR_GetRecoveredObject function to complete the recovery of an individual key.

NumberOfRecoveredKeys (output)

The number of keys in the cache.

RETURN VALUES

A CSSM_RETURN value indicating whether the operation returned a set of keys. If the result is CSSM_FAIL, and a NULL cache handle and a positive EstimatedTime are returned, then the calling application is expected to call this function again after the specified EstimatedTime. If the result is CSSM_FAIL and EstimatedTime is zero, an error has occurred. Use CSSM_GetError to obtain the error code.

ERRORS

CSSM_INVALID_KR_HANDLE

Invalid KR handle.

CSSM_KR_INVALID_HANDLE

Invalid reference handle.

CSSM_MEMORY_ERROR

Memory error.

CSSM_KR_FAIL

Function failed.