NAME
   sec_login_get_expiration - Returns the TGT lifetime for an
                              authenticated identity

 SYNOPSIS

 #include <dce/sec_login.h>

 void sec_login_get_expiration(
         sec_login_handle_t login_context,
         signed32 *identity_expiration,
         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.  (See sec_intro for more details
       about the login context.)

 Output

  identity_expiration
       The lifetime of the Ticket-Granting Ticket (TGT) belonging to
       the authenticated identity identified by login_context.  It can
       be used in the same ways as a UNIX time_t.

 status
       A pointer to the completion status.  On successful completion,
       the routine returns one of the following status codes:

        + error_status_ok to indicate that the login context has been
          validated and certified.

        + sec_login_s_not_certified to indicate that the login context
          has been validated, but not certified.  Although this code
          indicates successful completion, it warns you that the
          context is not validated.

 If the call does not complete successfully, it returns an error.

 DESCRIPTION

 The sec_login_get_expiration() routine extracts the lifetime for the
 TGT belonging to the authenticated identity contained in the login
 context.  The liftime value is filled in if available; otherwise, it
 is set to 0 (zero).  This routine allows an application to tell an
 interactive user how long the user's network login (and authenticated
 identity) will last before having to be refreshed.

 The routine works only on previously certified contexts.

 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 invalid.

 sec_login_s_default_use
              There was illegal use of the default login handle.

 sec_login_s_not_certified
              The login context has not been certified.

 sec_login_s_no_current_context
              The calling process has no context of its own.

 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. To avoid this
 situation, an application might, before initiating a long operation,
 use the sec_login package to check the expiration time of its identity
 and refresh it if there is not enough time remaining to complete the
 operation. After refreshing the identity, the process must validate it
 again with sec_login_validate_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)) {
            if (st == sec_login_s_refresh_ident_bad) {
               ... identity has changed ...
            } else {
               ... login context cannot be renewed ...
               exit(error_context_not_renewable);
            }

           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_get_current_context