openssl之BIO系列之5---CallBack函数及其控制

CallBack函数及其控制
    
    通过前面的介绍大家已经知道，BIO的callback函数是非常重要的，是实现BIO多态性的一个关键因素之一，BIO提供的callback控制系列函数有五个，其实都是一些宏定义，下面是它的声明和定义（openssl/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)
    其中，callback函数本身的声明如下：
     typedef long callback(BIO *b, int oper, const char *argp,
     int argi, long argl, long retvalue);
    此外，还有一个用于调试目的的函数，其实声明如下：
     long BIO_debug_callback(BIO *bio,int cmd,const char *argp,int argi,long argl,long ret);
    如果要看具体的例子，那么在文件crypto/bio/bio_cb.c的函数BIO_debug_callback() 本身就是一个非常好的例子。
    下面，我们从callback函数本身开始分别简单介绍这些函数的作用。
    
    【callback】
    callback函数在BIO中非常重要，许多控制功能都是要通过callbank函数协助完成的，比如BIO要执行释放的操作BIO_free，那么其实它是先调用callback函数设置下面的操作将是释放操作（控制码:BIO_CB_FREE），然后才调用别的相关函数执行真正的操作，在后面我们会列出这些控制功能函数，并简单说明callback函数是怎么在这些功能的实现中使用的。现在，我先简单介绍callback函数的各个参数：
    (参数名字参看说明的函数的声明)
    参数---b
    这是callback函数的输入参数，也就是callback函数对应的BIO
    参数---oper
    设置BIO将要执行的操作，有些操作，callback函数将被调用两次，一次实在实际操作之前，一次实在实际操作之后，在后面的调用的时候，一般是将oper和BIO_CB_RETURN相或操作后作为参数的。也就是说，后一次调用的时候oper参数应该使用oper|BIO_CB_RETURN。
    参数---argp, argi,argl
    这些参数根据oper定义的操作的不同而不一样，是在相应操作中要用到的参数。
    参数---retvalue
    这是默认的callback函数返回值，也就睡说，如果没有提供BIO没有提供相应的callback函数，那么就会返回这个值。真正的返回值是callback函数本身提供的。如果在实际的操作之前调用callback函数，并且这时候retvalue参数设置为1，如果callback的函数返回值无效，那么对callback函数的调用就会导致程序立刻返回，BIO的操作就不会执行。
    一般情况下，callback函数在执行完后都应该返回retvalue的值，除非该操作有特别的目的要修改这个返回值。
    下面简单列出我们比较熟悉的一些跟callback函数相关的BIO函数使用callback函数的情况：
    1.BIO_free(b)
    在执行该操作之前，调用了callback(b, BIO_CB_FREE, NULL, 0L, 0L, 1L)
    2.BIO_read(b,out,outl)
    在执行该操作之前，调用了callback(b, BIO_CB_READ, out, outl, 0L, 1L),之后调用了callback(b, BIO_CB_READ|BIO_CB_RETURN, out, outl, 0L,retvalue)，大家可以看到，这就是我们上面说明过的情况，即两次调用callback的操作，后面一次oper的参数需要或上BIO_CB_RETURN。
    3.BIO_write(b,in,inl)
    在执行该操作之前，调用了callback(b, BIO_CB_WRITE, in, inl, 0L, 1L),之后调用了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),之后调用了callback(b, BIO_CB_GETS|BIO_CB_RETURN, out, outl, 0L, retvalue)
    5.BIO_puts(b, in)
    在执行该操作之前，调用了callback(b, BIO_CB_WRITE, in, 0, 0L, 1L) ,之后调用了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),之后调用了callback(b,BIO_CB_CTRL|BIO_CB_RETURN,parg,cmd, larg,ret)
    
    【BIO_set_callback和BIO_get_callback】
    这两个函数用于设置和返回BIO中的callback函数，它们都是宏定义，根据前面的叙述我们已经知道，callback函数在许多高层的操作中都使用了，因为它能用于调试跟踪的目的或更改BIO的操作，具有很大的灵活性，所以这两个函数也就有用武之地了。
    【BIO_set_callback_arg和IO_get_callback_arg】
    顾名思义，这两个函数用了设置和得到callback函数中的参数。
    【BIO_debug_callback】

    这是一个标准的调试信息输出函数，它把相关BIO执行的所有操作信息都打印输出到制定的地方。如果callback参数没有指定输出这些信息的BIO口，那么就会默认使用stderr作为信息输出端口。

FW: http://blog.csdn.net/gdwzh/article/details/19198