set_app

NAME: set_app_ctx - per-thread global application context

SYNOPSIS

#include <set_msg.h>

int create_set_app_ctx(app_ctx, swIdent, log)
    set_app_ctx               *app_ctx;        /* OUT */
    asn1set__SWIdent          *swIdent;        /* IN */
    log_ctx                    log;            /* IN */

int delete_set_app_ctx(app_ctx)
    set_app_ctx   *app_ctx;                    /* IN/OUT */

int modify_set_app_ctx(app_ctx, modify /* , ... */ )
    set_app_ctx    app_ctx;                    /* IN */
    int            modify;                     /* IN */
    /* additional argument(s) */               /* IN */

#define SET_APP_CTX_MODIFY_SWIDENT               1  /*  asn__any*  */
#define SET_APP_CTX_MODIFY_MAX_CLOCK_SKEW        2  /*  int seconds  */
#define SET_APP_CTX_MODIFY_SUPPORT_TUNNELING     3  /*  int trueorfalse */ 
#define SET_APP_CTX_MODIFY_SUPPORT_INBAND_KEYS   4  /*  int trueorfalse */ 
#define SET_APP_CTX_MODIFY_EARLY_REPLAY_CHECK    5  /*  int trueorfalse */




int query_set_app_ctx(app_ctx, query /* , ... */ )
    set_app_ctx    app_ctx;                    /* IN */
    int            query;                      /* IN */
    /* additional argument(s) */               /* OUT */

#define SET_APP_CTX_QUERY_SWIDENT                1  /*  asn__any**  */
#define SET_APP_CTX_QUERY_MAX_CLOCK_SKEW         2  /*  int *seconds  */
#define SET_APP_CTX_QUERY_SUPPORT_ACQBACKINFO    3  /*  int *trueorfalse */ 
#define SET_APP_CTX_QUERY_SUPPORT_INBAND_KEYS    4  /*  int *trueorfalse */
#define SET_APP_CTX_QUERY_EARLY_REPLAY_CHECK     5  /*  int *trueorfalse */




/*
 *    DEFAULTS
 */
#define SET_APP_CTX_DEFAULT_MAX_CLOCK_SKEW       (2*60*60)    /* 2 hours */
#define SET_APP_CTX_DEFAULT_SUPPORT_TUNNELING    1            /* true */
#define SET_APP_CTX_DEFAULT_SUPPORT_INBAND_KEYS  1            /* true */
#define SET_APP_CTX_DEFAULT_EARLY_REPLAY_CHECK   0            /* false */

DESCRIPTION

The set_app_ctx context contains "global" data that is specific to a single thread, in order to support multithreaded applications. A single set_app_ctx cannot be shared among threads.

A set_app_ctx is independent of any message or transaction, so a single set_app_ctx can be used to process multiple messages or transactions concurrently.

create_set_app_ctx() is used to create and initialize a new set_app_ctx.

delete_set_app_ctx() deletes the context. Following a call to delete_set_app_ctx(), the set_app_ctx is no longer valid.

modify_set_app_ctx() and query_set_app_ctx() are used to modify and to query the configuration of the set_app_ctx.

PARAMETERS

create_set_app_ctx(): The textual string swIdent identifies the software package. In most cases, all instances of set_app_ctx will share the same swIdent.
SETREF expects there to be a single, global log file, which the application manages. The log contains primarily the RRPID and/or XID of each message that has been processed. This information is used to detect repeated or replayed messages. All set_app_ctx are expected to share the same log_ctx.

RETURN VALUES

create_set_app_ctx(): On success, returns NO_ERROR.
delete_set_app_ctx(): On success, returns NO_ERROR. On failure, it returns SET_ERR_BAD_PARAMETER.
modify_set_app_ctx(): On success, returns NO_ERROR. On failure, it returns SET_ERR_UNKNOWN_MODIFY or SET_ERR_MEMORY.
query_set_app_ctx(): On success, returns NO_ERROR. On failure, it returns SET_ERR_UNKNOWN_QUERY.

See Return Values for descriptions of individual error codes. For documentation on displaying or logging return values, see error_ctx.

SEE ALSO: set_msg, AuthReq, AuthRes, CapReq, CapRes, PInitReq, PInitRes, PReq, PRes

EXAMPLE

    #define TWO_MONTHS     (60*60*24*31*2)   /* 2 months' worth of seconds */
    
    int use_set_app_ctx()
    {
        asn1set__SWIdent swIdent[] = { { asn1set__SWIdent__printableString, 
                                         { "Terisa Demo Software v.beta1" } } };
        set_app_ctx             app_ctx    = 0;  /* per-thread global data */
        log_ctx                 history    = 0;  /* past-transaction info */
        int                     seconds;
    
        status = create_log_ctx_db(&history, "history.log");
        assert(status == NO_ERROR);
    
        /*  Create the thread-specific context, setting the default software
         *  identifier to "swIdent,"
         *
         *  The set_app_ctx context contains "global" data that is specific
         *  to a single thread, in order to support multithreaded 
         *  applications.  A single set_app_ctx may not be shared among
         *  threads.
         *
         *  A set_app_ctx is independent of any message or transaction, so
         *  a single set_app_ctx can be used to process multiple 
         *  messages or transactions concurrently.
         */ 
    
        status = create_set_app_ctx(&app_ctx, swIdent, history);
        assert(status == NO_ERROR);
    
        status = query_set_app_ctx(app_ctx, SET_APP_CTX_QUERY_MAX_CLOCK_SKEW, &seconds);
        assert(status == NO_ERROR);
        if (seconds < TWO_MONTHS) {
             status = modify_set_app_ctx(app_ctx, SET_APP_CTX_MODIFY_MAX_CLOCK_SKEW, TWO_MONTHS);
             assert(status == NO_ERROR);
        }

        /*  Process a message...  */
        ...

        /*  Delete the thread-specific global context.  If another
         *  message is going to be processed by this thread, even
         *  one that is part of another transaction, then app_ctx
         *  can be used to process that message, rather than being
         *  deleted.
         */

        status = delete_set_app_ctx(&app_ctx);
        assert(status == NO_ERROR);

        status = LOG_delete(&history);
        assert(status == NO_ERROR);

        return NO_ERROR;

BUGS: This document describes a beta implementation. The information contained in this document may be incomplete and is subject to change.