NAME
   sec_key_mgmt_initialize_cursor - Repositions the cursor in the local
                                    key store

 SYNOPSIS

 #include <dce/keymgmt.h>

 void sec_key_mgmt_initialize_cursor(
         sec_key_mgmt_authn_service authn_service,
         void *arg,
         idl_char *principal_name,
         void *keytype,
         void **cursor,
         error_status_t *status);

 PARAMETERS

 Input

 authn_service
        Identifies the authentication protocol using this key.  The
        possible authentication protocols are as follows:

        rpc_c_authn_dce_secret
                    DCE shared-secret key authentication.

        rpc_c_authn_dce_public
                    DCE public key authentication (reserved for future
                    use).

 arg    This parameter can specify either the local key file or an
        argument to the get_key_fn key acquisition routine of the
        rpc_server_register_auth_info routine.  A value of NULL specifies
        that the default key file (DCE$LOCAL:[KRB]V5SRVTAB.;) should be
        used.  A key file name specifies that file should be used as the
        key file.  You must prepend the file's absolute filename with
        FILE: and the file must have been created with the rgy_edit ktadd
        command or the sec_key_mgmt_set_key routine.
        Any other value specifies an argument for the get_key_fn key
        acquisition routine. See the rpc_server_register_auth_info()
        reference page for more information.

 principal_name
        A pointer to a character string indicating the name of the
        principal whose key is to be accessed. To access all keys in
        the local key store, supply NULL for this parameter.

 keytype
        A pointer to the data encryption algorithm (for example, DES)
        being used for the key.

 Output

 cursor
        The returned cursor value. The storage for the cursor information
        is allocated dynamically, so the returned pointer actually
        indicates a pointer to the cursor value.  The storage for this
        data may be freed with the sec_key_mgmt_release_cursor() routine.

 status
        A pointer to the completion status.  On successful completion,
        the routine returns error_status_ok.  Otherwise, it returns an
        error.

 DESCRIPTION

 The sec_key_mgmt_initialize_cursor() routine resets the cursor in the
 local key store.

 Use this routine to reposition the cursor before performing a scan of
 the local store via sec_key_mgmt_get_next_key().  The returned cursor
 value is supplied as input to sec_key_mgmt_get_next_key().

 FILES
       SYS$COMMON:[DCE$LIBRARY]KEYMGMT.IDL
              The idl file from which dce/keymgmt.h was derived.

 ERRORS

 sec_s_no_memory
               Unable to allocate memory.

 sec_key_mgmt_e_authn_invalid
              The authentication protocol is not valid.

 sec_key_mgmt_e_unauthorized
              The caller is not authorized to perform the operation.

 error_status_ok
              The call was successful.

 RELATED INFORMATION

 Functions: sec_intro
            sec_key_mgmt_get_next_key
            sec_key_mgmt_release_cursor