Callback function and its control
--- Translation according to OpenSSL DOC / CRYPTO / BIO / BIO_SET_CALLBACK.POD and its own understanding
(Author: DragonKing Mail: wzhah@263.net Posted: gdwzh.126.com openssl professional forum)
Through the previous introduction, everyone already knows that BIO's Callback function is very important. One of the key factors for implementing BIO polymorphism. There are five Callback control series functions provided by BIO, in fact, some macro definitions, below Its statement and definition (OpenSSSL / BIO.H):
#define bio_set_callback (b, cb) ((b) -> Callback = (CB))
#define bio_get_callback (b) ((b) -> Callback)
#define bio_set_callback_arg (b, arg) ((b) -> cb_arg = (char *) (arg))
#define bio_get_callback_arg (b) ((b) -> cb_arg)
Among them, the statement of the Callback function itself is as follows:
Typedf Long Callback (Bio * B, int Oper, const char * argp,
INT Argi, Long Argl, Long RetValue;
In addition, there is a function of debugging purposes, in fact, as follows:
Long Bio_Debug_callback (Bio * Bio, Int Cmd, Const Char * Argp, Int Argi, long argl, long Ret)
If you want to see a specific example, then the function BIO_DEBUG_CALLBACK () in the file CRYPTO / BIO / BIO_CB.C is itself a very good example.
Below, we have simply introduce these functions from the Callback function itself.
[Callback]
The Callback function is very important in the BIO. Many control functions are to be completed by the CallBank function, such as the BIO to perform the release of the Bio_Free, then it is actually called the Callback function setting below will be the release operation (control code: BIO_CB_FREE), then call other related functions to perform real operations, then we will list these control functions, and briefly explain how the Callback function is used in the implementation of these features. Now, I will briefly introduce the various parameters of the Callback function:
(Parameter name to see the documentation of the function)
Parameter --- B
This is the input parameters of the Callback function, that is, the Callback function corresponding to the Bio
Parameter --- Oper
Set the operation of the BIO to perform, some operations, the callback function will be called twice, before actual operation, at a time, after the actual operation, when the call is called, the Oper and BIO_CB_RETURN are used as a parameter after operation. . That is, the OPER parameter should use Oper | BIO_CB_RETURN when the last call is called.
Parameters --- Argp, Argi, Argl
These parameters are different depending on the operation of the OPER definition, is the parameters to be used in the respective operation.
Parameters - RetValue
This is the default Callback function returns a value, and I sleep, if I don't provide the BIO without providing the corresponding Callback function, then this value will be returned. The real return value is provided by the Callback function itself. If the callback function is called before actual operation, and this time the return parameter is set to 1. If the Callback function return value is invalid, then the call to the Callback function will cause the program to return, the BIO operation will not be executed. In general, the Callback function should return the value of RetValue after execution, unless the operation has a special purpose to modify this return value.
The following is simple to list the case where we are more familiar with some BIO functions that are related to the Callback function use the Callback function:
1.BIO_FREE (B)
Callback (B, BIO_CB_FREE, NULL, 0L, 0L, 1L) is called before executing this operation.
2.BIO_READ (B, OUT, OUTL)
Callback (B, BIO_CB_READ, OUT, OUTL, 0L, 1L) were called before executing this operation, then called Callback (B, Bio_CB_READ | BIO_CB_RETURN, OUT, OUTL, 0L, RETVALUE), everyone can see, this is The situation we have described above, that is, call the Callback operation twice, and the parameters of the following OPER are required or on BIO_CB_RETURN.
3.BIO_WRITE (B, IN, INL)
Callback (B, BIO_CB_WRITE, IN, INL, 0L, 1L) were called before executing this operation, then called Callback (B, Bio_CB_WRITE | BIO_CB_RETURN, IN, INL, 0L, RETVALUE)
4.BIO_GETS (B, OUT, OUTL)
Callback (B, BIO_CB_GETS, OUT, OUTL, 0L, 1L) were called before executing this operation, then called Callback (B, BIO_CB_GETS | BIO_CB_RETURN, OUT, OUTL, 0L, RETVALUE)
5.BIO_PUTS (B, IN)
Callback (B, Bio_CB_WRITE, IN, 0, 0, 0L, 1L) were called before executing this operation, then called Callback (B, BIO_CB_WRITE | BIO_CB_RETURN, IN, 0, 0L, RETVALUE)
6.BIO_CTRL (Bio * B, INT CMD, Long Larg, Void * Parg)
Callback (B, Bio_CB_CTRL, PARG, CMD, LARG, 1L) were called before executing this operation, and then Callback (B, BIO_CB_CTRL | BIO_CB_RETURN, PARG, CMD, LARG, RET) were called.
[BIO_SET_CALLBACK and BIO_GET_CALLBACK]
These two functions are used to set up and return to the Callback function in the BIO, they are all macro definitions, according to the previous narrative we already know, the Callback function is used in many high-level operations because it can be used to debug tracking purposes Or change the operation of BIO, with great flexibility, so these two functions are also used.
[BIO_SET_CALLBACK_ARG and IO_GET_CALLBACK_ARG]
As the name suggests, these two functions have used the parameters in the Callback function.
[BIO_DEBUG_CALLBACK]
This is a standard debug information output function, which prints all operation information performed by the associated BIO to the formulated place. If the Callback parameter does not specify the Bio port of the output this information, STDERR will be used by default as the information output port.
