RSA BSAFE Cert-C API Reference

Text Surrender Service Provider

Use the Cert-C Text Surrender service provider to surrender control of a Cert-C function to the application. Only one surrender service provider can be registered at a given time. The SURRENDER_FUNCS structure points to all the service-provider functions. Any implementation of the Text Surrender service provider is based on this structure. Click on the structure name for information on any of the members in this structure.

There is only one implementation of this service provider included in Cert-C. Other implementations can be developed, if necessary.

Implementation 1: Cert-C Text Surrender Service Provider

The Cert-C Text Surrender service provider is the Cert-C implementation of the Surrender service provider; it is suitable for use in console, command-line, or other text-mode applications. It implements all the functions in SURRENDER_FUNCS.

During lengthy operations such as public-key computations or key generation, Cert-C calls the Cert-C Text Surrender service provider. The Cert-C Text Surrender service provider indicates the progress of long-running operations by printing a series of characters to the screen. When this service provider is registered, the application is responsible for leaving the cursor at the beginning of a new line before calling any long-running Cert-C function.

To initialize or register the Cert-C Text Surrender service provider, call either the C_InitializeCertC or C_RegisterService function. Both functions take SERVICE_HANDLER as a parameter. The Initialize member in SERVICE_HANDLER points to the S_InitializeTextSurrender function and the corresponding parameter is NULL_PTR. This function initializes the Cert-C Text Surrender service provider's implementation of the surrender functions and stores pointers to them in the surrender member in SERVICE_FUNCS, which in turn points to the SURRENDER_FUNCS structure. S_InitializeTextSurrender is never called directly by the application.

Note: When referring to S_InitializeTextSurrender, be sure to include the textsurr.h header file. The key-pair sample program makes use of this service provider.