RSA BSAFE Micro Edition Suite

Streamlined security for mobile and embedded devices
Search  Print

Callback Functions

This section documents the functions provided for the utilization of user-defined callback routines to execute in BIO operations. User-defined callbacks can be associated with BIOs and subsequently invoked via the BIO library's API functions.

User-defined callbacks are associated with a BIO via BIO_set_cb(). The BIO library code also contains the pre-defined callback BIO_debug_cb() which provides a trace of BIO method calls.

The user-defined callback enables the application to trace the I/O statement execution for:


The following table details the callback argument descriptions.

Callback Argument Descriptions

Field Description
bio Pointer to the BIO.
info_code Bit field - gives function and return flag.
parg General pointer value for callback.
iarg General integer value for callback.
larg General long value for callback.
ret Current return status of method.

The callback must return a valid return code for the method:

If the info_code contains the BIO_CB_RETURN value, the callback function is a post-method callback. In this situation, the ret argument is the return value from the method.

parg, iarg , iarg and larg supply values to the callback. For example, parg is often used to pass any of the method's pointer arguments to the callback. Similarly the larg passes a long argument for the method to the callback.

These actions depend on the coding of the BIO_xxx call because the callback is called from this function. Generally user data required by a callback can be set against the BIO's field and directly referenced by the callback code.

The supplied values indicate which function is making the call. This value is supplied to both the before and after calls. The after call value is combined with BIO_CB_RETURN to indicate it is after the method call.

Typedefs

typedef long R_CDECL BIO_CB_FUNC_T (BIO *bio, int cmd, char *argp, int argi, long argl, long ret)
 Used for creating user-defined debugging routines or surrender functions. More...

typedef long R_CDECL R_BIO_CB_FUNC_T (BIO *bio, int cmd, char *argp, int argi, long argl, long ret)
 Deprecated name for the BIO callback type.

typedef int R_CDECL BIO_STATE_CB_FUNC_T (BIO *bio, int type, int state, int ret, int flag, char *cb_arg)
 The type of callback function that reports on the BIO state. More...

typedef struct bio_state_cb_st BIO_STATE_CB
 The type used to hold the state callback and its user-defined argument for transportation.


Functions

void R_CDECL BIO_set_cb (BIO *bio, BIO_CB_FUNC_T *cb)
 Sets a user-defined callback for the BIO bio. More...

void R_CDECL BIO_set_cb_arg (BIO *bio, char *arg)
 Sets an extra user-defined argument against the BIO bio that developers may use in the callback. More...

void R_CDECL BIO_set_bio_cb (BIO *bio, BIO_CB_FUNC_T *cb, char *arg)
 Sets the BIO callback and an argument against the BIO bio. More...

char* R_CDECL BIO_get_cb_arg (BIO *bio)
 Returns a pointer to the user-defined data for the user-defined callback that exists within the BIO bio. More...

BIO_CB_FUNC_T* R_CDECL BIO_get_cb (BIO *bio)
 Returns the user-defined callback function for the BIO bio if a callback function is defined. More...

void R_CDECL BIO_set_state_cb (BIO *bio, BIO_STATE_CB_FUNC_T *cb, char *arg)
 Sets the BIO state callback and an argument against the BIO bio. More...

int R_CDECL BIO_state_to_string (BIO *bio, int state, unsigned int len, char *str)
 Converts the state value of the internal state machine of the BIO into a string. More...

char* R_CDECL BIO_get_state_cb_arg (BIO *bio)
 Returns a pointer to the user-defined data for the user-defined state callback that exists within the BIO bio. More...

BIO_STATE_CB_FUNC_T* R_CDECL BIO_get_state_cb (BIO *bio)
 Returns the user-defined state callback function for the BIO bio if a state callback function is defined. More...

int R_CDECL BIO_set_cb_recursive (BIO *bio, int type, void *cb, char *arg)
 Sets the BIO state callback and an argument against all the BIO objects in the stack. More...

int R_CDECL BIO_flags_to_string (int flags, char sep, unsigned int len, char *str)
 Converts the flags of a BIO into a string. More...

int R_CDECL BIO_cb_cmd_to_string (int cmd, unsigned int len, char *str)
 Converts the information callback cmd for a BIO into a string. More...

Typedef Documentation

typedef long R_CDECL BIO_CB_FUNC_T(BIO *bio, int cmd, char *argp, int argi, long argl, long ret)
 

Used for creating user-defined debugging routines or surrender functions. The command value is a bit-wise combination of a command flag and a timing flag value. The command value is dependent upon the BIO command. The timing value BIO_CB_RETURN is included if the callback is invoked after the BIO method.

Parameters:
bio [In] A reference to the BIO.
cmd [In] The BIO command identifier.
argp [In] A pointer argument used for arbitrary data.
argi [In] The integer argument.
argl [In] The long argument.
ret [In] The status of the current operation on the BIO.
Returns:
1 indicates success.
Otherwise indicates error.
See also:
BIO_get_cb(), BIO_set_cb_arg(), BIO_set_bio_cb(), BIO_get_cb_arg() and BIO_set_cb().

typedef int R_CDECL BIO_STATE_CB_FUNC_T(BIO *bio, int type, int state, int ret, int flag, char *cb_arg)
 

The type of callback function that reports on the BIO state.

Parameters:
bio [In] A BIO reference.
type [In] The type of BIO.
state [In] The current BIO state.
ret [In] The current success flag. One of:
  • -1 indicates an error occurred.
  • 0 indicates the end of file.
  • >0 indicates the number of Bytes read.
    • flag [In] The current flags associated with the error.
    cb_arg [In] The user callback argument.
    Returns:
    1 indicates success.
    0 indicates error.

    Function Documentation

    int R_CDECL BIO_cb_cmd_to_string (  int    cmd,
    unsigned int    len,
    char *    str
    )  ;
     

    Converts the information callback cmd for a BIO into a string.

    Parameters:
    cmd [In] The command indicating where the callback is occurring.
    len [In] The length of string into which to write.
    str [Out] The string into which to write.
    Returns:
    The operation status. One of:
  • 1 indicates success.
  • 0 indicates error.
    • note.gif
    If the function needs to write more than len characters into the string str, it will write len characters, including the terminating character, and return the error R_ERROR_BUFFER_TOO_SMALL.

    int R_CDECL BIO_flags_to_string (  int    flags,
    char    sep,
    unsigned int    len,
    char *    str
    )  ;
     

    Converts the flags of a BIO into a string.

    Parameters:
    flags [In] The flags indicating the error reasons.
    sep [In] A character to use to separate the flag strings.
    len [In] The length of the string into which to write.
    str [Out] The string into which to write.
    Returns:
    The operation status. One of:
  • 1 indicates success.
  • 0 indicates error.
    • note.gif
    If the function needs to write more than len characters into the string str, it will write len characters, including the terminating character, and return the error R_ERROR_BUFFER_TOO_SMALL.

    BIO_CB_FUNC_T* R_CDECL BIO_get_cb (  BIO *    bio )  ;
     

    Returns the user-defined callback function for the BIO bio if a callback function is defined.

    Parameters:
    bio [In] A reference to the BIO.
    Returns:
    A pointer to a function that returns a user-defined callback.
    NULL indicates no callback was defined.
    See also:
    BIO_set_cb() and BIO_set_cb_arg().

    char* R_CDECL BIO_get_cb_arg (  BIO *    bio )  ;
     

    Returns a pointer to the user-defined data for the user-defined callback that exists within the BIO bio.

    Parameters:
    bio [In] A reference to the BIO.
    Returns:
    A data pointer to the callback argument.
    NULL indicates no data was defined.
    See also:
    BIO_set_cb_arg().

    BIO_STATE_CB_FUNC_T* R_CDECL BIO_get_state_cb (  BIO *    bio )  ;
     

    Returns the user-defined state callback function for the BIO bio if a state callback function is defined.

    Parameters:
    bio [In] A reference to the BIO.
    Returns:
    A pointer to a function that returns a long.
    NULL indicates no callback was defined.
    See also:
    BIO_get_state_cb_arg(), BIO_set_state_cb() and BIO_CB_FUNC_T.

    char* R_CDECL BIO_get_state_cb_arg (  BIO *    bio )  ;
     

    Returns a pointer to the user-defined data for the user-defined state callback that exists within the BIO bio.

    Parameters:
    bio [In] A reference to the BIO.
    Returns:
    A data pointer to the state callback argument.
    NULL indicates no data was defined.
    See also:
    BIO_get_state_cb(), BIO_set_state_cb() and BIO_CB_FUNC_T.

    void R_CDECL BIO_set_bio_cb (  BIO *    bio,
    BIO_CB_FUNC_T *    cb,
    char *    arg
    )  ;
     

    Sets the BIO callback and an argument against the BIO bio.

    Parameters:
    bio [In] A reference to the BIO.
    cb [In] The user-defined callback function.
    arg [In] The callback argument.
    note.gif
    If bio or arg is NULL, the existing value is removed from the BIO.
    See also:
    BIO_set_cb(), BIO_set_cb_arg() and BIO_CB_FUNC_T.

    void R_CDECL BIO_set_cb (  BIO *    bio,
    BIO_CB_FUNC_T *    cb
    )  ;
     

    Sets a user-defined callback for the BIO bio. If NULL, any previous callback is removed from the BIO.

    Parameters:
    bio [In, Out] A reference to the BIO.
    cb [In] The user-defined callback.
    note.gif
    The callback is called both before and after the majority of BIO method calls, including the functions BIO_read(), BIO_write(), BIO_puts(), BIO_gets() and BIO_ctrl(). However, it is only called before the BIO_free() method call.
    The callback is often used for debugging BIO operations.
    See also:
    BIO_get_cb(), BIO_set_cb_arg(), BIO_set_bio_cb(), BIO_CB_FUNC_T and BIO_get_cb_arg().
    Example:

    /* $Id: bio_set_cb.c,v 1.3 2003/06/03 01:51:58 cmueller Exp $ */
/*
 * Copyright (C) 1998-2003 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.
 */
int cb_count = 0;

/* Create a new BIO via BIO_new */

/* Set the callback and the callback argument */
BIO_set_cb(bio, my_debug);
BIO_set_cb_arg(bio, (char *)&cb_count);

/* Create a BIO call that will trigger the callback */
BIO_free(bio);

printf("the number of times the callback was made = %d\n", cb_count);


/* Callback definition */
long my_debug(BIO *b, int cmd, char *argp, int argi, long argl, long ret)
{
    int *arg_ptr;

    /* Retrieve the callback argument */
    arg_ptr = (int *)BIO_get_cb_arg(b);

    /* Count the number of times called */
    (*arg_ptr)++;

    /* Return value of the calling function */
    return(ret);
}
    Samples:
    bio_client.c, bio_server.c, cache_server.c, nbio_client.c, nbio_server.c, p7ssl_client.c, p7ssl_server.c, sock_client.c, sock_server.c, ssl_client.c, and ssl_server.c.

    void R_CDECL BIO_set_cb_arg (  BIO *    bio,
    char *    arg
    )  ;
     

    Sets an extra user-defined argument against the BIO bio that developers may use in the callback. If the argument passed is NULL, the existing callback argument is cleared from the BIO.

    Parameters:
    bio [In, Out] A reference to the BIO.
    arg [In] The callback argument.
    See also:
    BIO_set_cb(), BIO_set_bio_cb(), BIO_CB_FUNC_T and BIO_get_cb_arg().
    Samples:
    bio_client.c, bio_server.c, cache_server.c, nbio_client.c, nbio_server.c, p7ssl_client.c, p7ssl_server.c, sock_client.c, sock_server.c, ssl_client.c, and ssl_server.c.

    int R_CDECL BIO_set_cb_recursive (  BIO *    bio,
    int    type,
    void *    cb,
    char *    arg
    )  ;
     

    Sets the BIO state callback and an argument against all the BIO objects in the stack.

    Parameters:
    bio [In] A reference to the BIO.
    type [In] The type of BIO callback function.
    See Callback Types for valid values.
    cb [In] The user-defined state callback function.
    arg [In] The state callback argument.
    See also:
    BIO_set_cb(), BIO_set_info_cb(), BIO_set_state_cb(), BIO_CB_FUNC_T and BIO_STATE_CB_FUNC_T.

    void R_CDECL BIO_set_state_cb (  BIO *    bio,
    BIO_STATE_CB_FUNC_T *    cb,
    char *    arg
    )  ;
     

    Sets the BIO state callback and an argument against the BIO bio.

    Parameters:
    bio [In] A reference to the BIO.
    cb [In] The user-defined state callback function.
    arg [In] The state callback argument.
    note.gif
    If bio or arg is NULL, the existing value is removed from the BIO.
    See also:
    BIO_get_state_cb_arg(), BIO_get_state_cb() and BIO_STATE_CB_FUNC_T.

    int R_CDECL BIO_state_to_string (  BIO *    bio,
    int    state,
    unsigned int    len,
    char *    str
    )  ;
     

    Converts the state value of the internal state machine of the BIO into a string.

    Parameters:
    bio [In] A reference to the BIO.
    state [In] The state of the BIO state machine.
    len [In] The length of the string into which to write.
    str [Out] The string into which to write.
    Returns:
  • 1 indicates success.
  • 0 indicates failure.

    • Copyright (c) 1999-2005 RSA Security Inc. All rights reserved. 072-001001-2100-001-000 - 2.1