RSA BSAFE Cert-C Micro Edition

The power of PKI for the smallest of devices

r_lib.h

Go to the documentation of this file.

/* $Id: r_lib.h,v 1.40 2002/10/16 06:22:09 jmckee Exp $ */
/*
 * Copyright (C) 1998-2002 RSA Security Inc. All rights reserved.
 *
 * This work contains proprietary information of RSA Security.
 * Distribution is limited to authorized licensees of RSA
 * Security. Any unauthorized reproduction, distribution or
 * modification of this work is strictly prohibited.
 *
 */
/**
 * @file
 * This file provides information on the structures, function prototypes and
 * defines used in the manipulation of library context objects.
 */
#ifndef HEADER_COMMON_R_LIB_H
#define HEADER_COMMON_R_LIB_H

#ifdef  __cplusplus
extern "C" {
#endif

#include "r_com.h"
#include "r_flg.h"
#include "r_strtbl.h"

#ifndef NO_BIO
#include "bio.h"
#endif

/**
 * @defgroup RES_LIST_GROUP Resource List Module
 * This section provides information on the resource list, which is used to
 * perform link and runtime implementation selection of modules.
 * @{
 */
/**
 * @}
 */
/**
 * @defgroup RES_LIST_TYPE Types
 * This section outlines the types used when dealing with the library and
 * the resources within.
 * @ingroup RES_LIST_GROUP
 *
 * @{
 */
/**
 * The common library context. This opaque structure is created via
 * R_LIB_CTX_new() and is required by all other #R_LIB_CTX
 * functions. It maintains the state required by the library
 * during execution. It can be freed via R_LIB_CTX_free() when it is no
 * longer required. Under normal circumstances only one context is
 * needed at a time.
 */
#ifndef HEADER_COMMON_R_LIB_CTX_TYPEDEF_DEF
#define HEADER_COMMON_R_LIB_CTX_TYPEDEF_DEF
typedef struct r_lib_ctx_st                     R_LIB_CTX;
#endif
/* end defgroup RES_LIST_TYPE */
/**
 * @}
 */

#ifndef HEADER_COMMON_R_RES_ITEM_TYPEDEF_DEF
#define HEADER_COMMON_R_RES_ITEM_TYPEDEF_DEF

/**
 * The resource item. A structure that is used to store the
 * individual members of a resource list.
 */
typedef struct r_res_item_st                    R_RES_ITEM;
#endif

#ifndef HEADER_COMMON_R_RES_LIST_TYPEDEF_DEF
#define HEADER_COMMON_R_RES_LIST_TYPEDEF_DEF
/**
 * The resource list. A structure that is used to store the
 * resource list.
 *
 * See @ref R_RES_ITEM.
 */
typedef R_RES_ITEM                              R_RES_LIST;
#endif

#ifndef HEADER_COMMON_R_RES_FLAG_TYPEDEF_DEF
#define HEADER_COMMON_R_RES_FLAG_TYPEDEF_DEF
/**
 * Indicates the type of the resource flag.
 */
typedef int                                     R_RES_FLAG;
#endif

/**
 * The library method table. An opaque structure that contains
 * the methods for the #R_LIB_CTX functions.
 */
typedef struct r_lib_method_st                  R_LIB_METHOD;

/** 
 *  The library context debug structure which is used to define the type of
 *  debugging required and the location where the debug information is
 *  sent.
 */

typedef struct r_lib_debug_st
        {
        R_FLG dbg_flg;
#ifndef NO_BIO
        BIO *bio;
#else
        void *bio;
#endif
        } R_LIB_DEBUG;

/** 
 *  The library context feature structure which is used to store the state of
 *  the library features.
 */
typedef struct r_lib_feat_st
        {
        unsigned long feature;
        } R_LIB_FEAT;

/* Feature hash defines */
#define R_LIB_FEATURE_LOCKING                   0x00000001L
/**
 * @defgroup RES_LIST_FN Operation Functions
 * This section outlines the functions used for initialization and 
 * manipulation of the #R_LIB_CTX and resources used within.
 * @ingroup RES_LIST_GROUP
 *
 * @{
 */
/* Get string defines */
#define R_LIB_CTX_get_error_string(lib_ctx,mod_id,code)         \
        R_LIB_CTX_get_string(lib_ctx,mod_id,R_RES_SUB_ID_ERROR_STRINGS,code)
#define R_LIB_CTX_get_reason_string(lib_ctx,mod_id,code)        \
        R_LIB_CTX_get_string(lib_ctx,mod_id,R_RES_SUB_ID_REASON_STRINGS,code)
#define R_LIB_CTX_get_detail_string(lib_ctx,mod_id,code)        \
        R_LIB_CTX_get_string(lib_ctx,mod_id,R_RES_SUB_ID_DETAIL_STRINGS,code)
#define R_LIB_CTX_get_function_string(lib_ctx,mod_id,code)      \
        R_LIB_CTX_get_string(lib_ctx,mod_id,R_RES_SUB_ID_FUNCTION_STRINGS,code)


int R_LIB_CTX_new(R_RES_LIST *r_list, R_RES_FLAG flag, R_LIB_CTX **lib_ctx);
int R_LIB_CTX_free(R_LIB_CTX *lib_ctx);
int R_LIB_CTX_dup(R_LIB_CTX *lib_ctx, R_RES_FLAG flag, R_LIB_CTX **res_ctx);

int R_LIB_CTX_get_resource(R_LIB_CTX *res_ctx, int mod_id, int impl_id,
        int sub_id, R_RES_FLAG flag, int res_type, void **data);
int R_LIB_CTX_get_module(R_LIB_CTX *res_ctx, int mod_id, int impl_id,
        int sub_id, R_RES_FLAG flag, void **mod);
int R_LIB_CTX_get_module_data(R_LIB_CTX *lib_ctx, int mod_id, 
    void **impl_data);

int R_LIB_CTX_set_features(R_LIB_CTX *lib_ctx, int impl_id,
        unsigned long features);
int R_LIB_CTX_reset_features(R_LIB_CTX *lib_ctx, int impl_id);
int R_LIB_CTX_retrieve_features(R_LIB_CTX *lib_ctx, int impl_id,
        unsigned long *features);
unsigned long R_LIB_CTX_get_features(R_LIB_CTX *lib_ctx, int impl_id);
int R_LIB_CTX_feature_disable(R_LIB_CTX *lib_ctx, int impl_id,
        unsigned long feature);
int R_LIB_CTX_feature_enable(R_LIB_CTX *lib_ctx, int impl_id,
        unsigned long feature);
int R_LIB_CTX_is_feature_enabled(R_LIB_CTX *lib_ctx, int impl_id,
        unsigned long feature);

int R_LIB_CTX_get_lib_debug_data(R_LIB_CTX *lib_ctx, R_LIB_DEBUG **data);
int R_LIB_CTX_set_lib_debug_data(R_LIB_CTX *lib_ctx, R_LIB_DEBUG *data);

R_RES_LIST *R_LIB_CTX_get_resource_list(R_LIB_CTX *lib_ctx);

R_LIB_METHOD *R_LIB_CTX_get_default_method(void *imp_data);
R_LIB_METHOD *R_LIB_CTX_get_small_method(void *imp_data);

R_STRTBL *R_LIB_CTX_com_err_str_table(void *imp_data);

int R_LIB_CTX_lib_debug_data_start(R_RES_LIST *res_list, R_RES_ITEM *item,
        void **imp_data);
int R_LIB_CTX_lib_feature_start(R_RES_LIST *res_list, R_RES_ITEM *item,
        void **imp_data);

char *R_LIB_CTX_get_string(R_LIB_CTX *lib_ctx, int mod_id, int table_id,
        int err_code);

/* end defgroup RES_LIST_FN */
/**
 * @} 
 */

/**
 * @defgroup R_LIB_RES Library Definitions
 * This section details the definitions used in the resource list and
 * initialization of the library.
 * @ingroup RES_LIST_GROUP
 *
 * @{
 */

/**
 * A cut-down library interface that only supports the <tt>get_resource</tt>,
 * <tt>get_module</tt> and <tt>get_module_data</tt> methods of the #R_LIB_CTX
 * interface.
 *
 * @see R_LIB_CTX_get_small_method().
 */
#define R_LIB_RES_SMALL                                              \
        { R_RES_MOD_ID_LIBRARY, R_RES_IMPL_ID_DEF, R_RES_SUB_ID_DEF, \
          R_RES_FLAG_DEF, NULL, NULL,                                \
          (void *(*)(void *))R_LIB_CTX_get_small_method, NULL }

/**
 * Indicates the full #R_LIB_CTX interface.
 * @see R_LIB_CTX_get_default_method().
 */
#define R_LIB_RES_DEFAULT                                            \
        { R_RES_MOD_ID_LIBRARY, R_RES_IMPL_ID_DEF, R_RES_SUB_ID_DEF, \
          R_RES_FLAG_DEF, NULL, NULL,                                \
          (void *(*)(void *))R_LIB_CTX_get_default_method, NULL }

/**
 * Textual descriptions of common error codes. This is only required if using
 * R_LIB_CTX_get_string() string functions.
 *
 * @see R_LIB_CTX_com_err_str_table().
 */
#define R_LIB_RES_ERROR_STRINGS                                            \
    { R_RES_MOD_ID_LIBRARY, R_RES_IMPL_ID_DEF, R_RES_SUB_ID_ERROR_STRINGS, \
      R_RES_FLAG_DEF, NULL, NULL, NULL,                                    \
      (void *(*)(void *))R_LIB_CTX_com_err_str_table }

/**
 * @}
 */

#ifdef  __cplusplus
}
#endif

#endif /* HEADER_COMMON_R_LIB_H */

---

Copyright (c) 1999-2002 RSA Security Inc. All rights reserved. 061-001005-150-001-000-3768 - 1.5