RSA BSAFE Cert-C API Reference

SURRENDER_FUNCS Reference

Use the SURRENDER_FUNCS structure to store pointers to the surrender service provider functions in Cert-C.

In this case, there is one implementation, the Cert-C Text Surrender Service Provider.

Use S_InitializeTextSurrender() to initialize the function pointers in surrender of funcs. The surrender contains pointers to functions implemented by the Cert-C Text Surrender Service Provider, following the specifications of the text surrender service provider interface.

#include <surrspi.h>

typedef struct surrender_funcs {
  void (*Finalize) (
    CERTC_CTX ctx,           /* Cert-C context */
    POINTER   handle);       /* provider handle */

  int (*Surrender) (
    POINTER handle);          /* provider handle */

  void (*Reset) (
    CERTC_CTX ctx,            /* Cert-C context */
    POINTER   handle);        /* provider handle */
} SURRENDER_FUNCS;

Data Fields
void(*	Finalize )(CERTC_CTX ctx, POINTER handle)
	Frees any resources associated with the service provider's handle, including freeing memory allocated during the service provider's initialization. More...
int(*	Surrender )(POINTER handle)
	Cert-C calls the Surrender function during Cert-C and Crypto-C operations that may take an extended amount of time to complete. More...
void(*	Reset )(CERTC_CTX ctx, POINTER handle)
	Cert-C calls the Reset function each time C_GetSurrenderCtx() is called. More...

---

Field Documentation (alphabetical)

void(* surrender_funcs::Finalize)( CERTC_CTX ctx, POINTER handle)

Frees any resources associated with the service provider's handle, including freeing memory allocated during the service provider's initialization. Cert-C calls Finalize when a service provider's instance is unregistered. This function is implemented by the Cert-C Text Surrender Service Provider.

void(* surrender_funcs::Reset)( CERTC_CTX ctx, POINTER handle)

Cert-C calls the Reset function each time C_GetSurrenderCtx() is called. This signals the beginning of a new Cert-C or Crypto-C operation that may take an extended amount of time to complete. In this way, the Cert-C Text Surrender Service Provider can prepare for subsequent Surrender calls. For example, the service provider may want to visually indicate the beginning of a new long-running operation. When the Surrender function is called at least once since the last reset, the Reset function moves the cursor to the beginning of a new line. It resets the state of the service provider so that the next Surrender call prints a left square bracket ([) and an asterisk (*). This function is implemented by the Cert-C Text Surrender Service Provider. Parameters: ctx This input parameter points to an initialized Cert-C context handle. handle This input parameter points to a copy of the handle returned by the Cert-C Text Surrender Service Provider initialization function. Returns: None.

int(* surrender_funcs::Surrender)( POINTER handle)

Cert-C calls the Surrender function during Cert-C and Crypto-C operations that may take an extended amount of time to complete. If the Surrender context returns zero, the calling function continues normally. If the Surrender context returns a non-zero value, the operation is canceled, and control returns to the application. The absence of a Cert-C context parameter ensures backward compatibility with surrender functions intended for use with previous versions of BSAFE products. The first time Cert-C calls the Surrender function after a Reset, a left square bracket ([) and an asterisk (*) are printed at the beginning of a new line. Subsequent Surrender calls each print one additional asterisk until 20 have been printed. Then, a right square bracket (]) is printed and the cursor is moved to the beginning of the current line. The sequence repeats but now prints from 1 to 20 periods. A series of periods (.) is followed by a series of plus characters (+), then a series of minus characters (-). After that, the service provider starts over again with asterisks. This function is implemented by the Cert-C Text Surrender Service Provider. Parameters: handle This input parameter is the service provider handle for the service provider instance to be surrendered; it was returned by the service provider's initialization function. Returns: If the Surrender context returns a non-zero value, the operation is canceled, and control returns to the application.

---

The documentation for this struct was generated from the following file:

• surrspi.h

---

RSA BSAFE^® Cert-C 2.7 API Reference