NAME
   sec_login_refresh_identity - Refreshes an authenticated identity for
                                a login context

 SYNOPSIS

 #include <dce/sec_login.h>

 boolean32 sec_login_refresh_identity(
         sec_login_handle_t login_context,
         error_status_t *status);

 PARAMETERS

 Input

 login_context
        An opaque handle to login context data. The login context
        contains, among other data, the account principal name and
        UUID, account restrictions, records of group membership, and
        the process home directory.

 Output

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

 DESCRIPTION

 The sec_login_refresh_identity() routine refreshes a previously
 established identity.  It operates on an existing valid context, and
 cannot be used to change credentials associated with that identity.
 The refreshed identity reflects changes that affect ticket lifetimes,
 but not other changes.  For example, the identity will reflect a change
 to maximum ticket lifetime, but not the addition of the identity as a
 member to a group.  Only a DCE login reflects all administrative
 changes made since the last login.

 The refreshed identity must be validated with
 sec_login_validate_identity() before it can be used.

 It is an error to refresh a locally authenticated context.

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

 ERRORS

 sec_login_s_context_invalid
              The login context itself is not valid.

 sec_login_s_default_use
              Illegal use of the default login handle occurred.

 sec_login_s_no_memory
              Not enough memory is available to complete the operation.

 error_status_ok
              The call was successful.

 EXAMPLES

 Since the authenticated network identity for a process has a finite
 lifetime, there is a risk it will expire during some long network
 operation, preventing the operation from completing.

 For a server application that must run with an authenticated network
 identity because they themselves sometimes act as clients of another
 server, the sec_login calls can be used to check the network identity
 expiration date, run sec_login_refresh_identity and
 sec_login_validate_identity before the expiration.  This will prevent
 interruptions in the server's operation due to the restrictions in
 network access applied to an unauthenticated identity.

      sec_login_get_expiration(login_context, &expire_time, &st);

      if (expire_time < (current_time + operation_duration)) {

         if (!sec_login_refresh_identity(login_context, &st)) {
               ... login context cannot be renewed ...
               ... sleep and try again ....
            }

      } else {

           if (sec_login_validate_identity(login_context, password,
                                  &reset_passwd, &auth_src, &st)) {
               ... identity validated ...
            } else {
               ... validation failed ...
               exit(error_validation_failure);
            }
         }
      }

      operation();

 RELATED INFORMATION

 Functions: sec_intro
            sec_login_validate_identity