iis的isapi接口简介

isapi（internet?server?application?programming?interface）作为一种可用来替代cgi的方法，是由微软和process软件公司联合提出的web服务器上的api标准。isapi与web服务器结合紧密，功能强大，能够获得大量的信息，因此利用isapi可以开发出灵活高效的web服务器增强程序。由于isapi程序与web服务器的关系，使得isapi接口在安全方面有一定的研究价值。本文主要讨论isapi在iis和vc++?6.0中的实现。?

一、isapi接口和cgi接口的不同。?

isapi程序和cgi程序完成类似的功能，但是实现方法不同。?

1、isapi程序以dll形式被web服务器加载到自己的进程空间中，因此和服务器共用同一个地址空间，且在没有客户请求时可以将其从内存中卸载；而对客户端发来的每个对cgi程序的请求则需要服务器为它单独启动一个进程，这需要耗费大量的时间和内存。当并发的请求数目很大时，使用cgi在效率上不如isapi。?

2、cgi程序通过环境块和标准输入输出与web服务器进行通信，而isapi程序与服务器结合得更为紧密，与服务器共享同一个进程上下文，主要通过一个参数块与服务器进行交互，可以从服务器那里获得关于当前http连接的大量信息。?

isapi主要分为isa和isapi?filter两部分。isa方法相对而言要传统一些，利用一些特殊的链接，指向服务器的作业，供程序开发人员设计一些扩展功能；而isapi过滤器则倾向于构造服务器直接调用的模块，提供一种无缝链接部件用于监测直接来自于服务器的http请求。?


二、isa?

isa（internet?server?application）也可称为isapi?dll，其功能和cgi程序的功能直接相对应，使用方法和cgi也类似，由客户端在url中指定其名称而激活。例如下面的请求将调用服务器的虚拟可执行目录scripts下的function.dll（isapi?dll必须放在服务器的虚拟可执行目录下）：?
http://www.abc.com/scripts/function.dll??

isa和服务器之间的接口主要有两个：getextentionversion(?)和httpextentionproc(?)。任何isa都必须在其pe文件头的引出表中定义这两个引出函数，以供web服务器在适当的时候调用。?

1、当服务器刚加载isa时，它会调用isa提供的getextentionversion(?)来获得该isa所需要的服务器版本，并与自己的版本相比较，以保证版本兼容。函数原型如下：?

bool?winapi?getextentionversion(hse_version_info?*version)；?
typedef?struct?_hse_version_info?
{?
dword?dwextensionversion;?//版本号?
char?lpszextensiondesc[hse_max_ext_dll_name_len];?//关于isa的描述字符串?
}?hse_version_info,?*lphse_version_info;?

2、isa的真正入口是httpextentionproc(?)，它相当于普通c程序的main(?)函数，在这个函数中根据不同的客户请求作不同的处理。服务器和httpextentionproc(?)之间是通过扩展控制块（extention?control?block）来进行通信的，即ecb中存放入口参数和出口参数，包括服务器提供的几个回调函数的入口地址。函数原型如下：?

dword?httpextensionproc(?extension_control_block?*pecb?);?

ecb的结构定义如下（in表示入口参数，out表示出口参数）：?

typedef?struct?_extension_control_block?
{?
dword?cbsize;?//in，本结构的大小，只读?
dword?dwversion?//in，版本号，高16位为主版本号，低16位为次版本号?
hconn?connid;?//in，连接句柄，由服务器分配，isa只能读取该值?
dword?dwhttpstatuscode;?//out，当前完成的事务状态?
char?lpszlogdata[hse_log_buffer_len];?//out，需要写入到日志文件中的内容?
lpstr?lpszmethod;?//in，等价于cgi的环境变量request_method?
lpstr?lpszquerystring;?//in，等价于环境变量query_string?
lpstr?lpszpathinfo;?//in，等价于环境变量path_info?
lpstr?lpszpathtranslated;?//in，等价于环境变量path_translated?
dword?cbtotalbytes;?//in，等价于环境变量content_length?
dword?cbavailable;?//in，缓冲区中的可用字节数?
lpbyte?lpbdata;?//in，缓冲区指针，指向客户端发来的数据?
lpstr?lpszcontenttype;?//in，等价于环境变量content_type?

//回调函数，用于返回服务器的连接信息或特定的服务器详细情况?
bool?(?winapi?*?getservervariable?)?
(?hconn?hconn,?
lpstr?lpszvariablename,?
lpvoid?lpvbuffer,?
lpdword?lpdwsize?);?

bool?(?winapi?*?writeclient?)?//回调函数，从客户端的http请求中读取数据?
(?hconn?connid,?
lpvoid?buffer,?
lpdword?lpdwbytes,?
dword?dwreserved?);?

bool?(?winapi?*?readclient?)?//回调函数，向客户端发送数据?
(?hconn?connid,?
lpvoid?lpvbuffer,?
lpdword?lpdwsize?);?

bool?(?winapi?*?serversupportfunction?)?//回调函数，访问服务器的一般和特定功能?
(?hconn?hconn,?
dword?dwhserrequest,?
lpvoid?lpvbuffer,?
lpdword?lpdwsize,?
lpdword?lpdwdatatype?);?

}?extension_control_block,?*lpextension_control_block;?

在上述ecb中，服务器不但提供了当前http连接的句柄和一些变量，而且提供了4个回调函数给isa调用，从而使isa可以获得更详尽的信息。?

三、isapi?filter?

isapi?filter位于服务器和客户端之间，能够对服务器和客户端之间的通信进行预处理和后处理，比如对通信进行加密/解密、提供对客户进行身份验证的新方法、提供自定义的日志记录等，在cgi中没有与isapi?filter直接相对应的部分。?

isapi?filter与服务器之间的接口有两个：getfilterversion(?)和httpfilterproc(?)。任何?
isapi?filter都必须引出这两个函数以供服务器调用。?

1、在注册表的如下键值中存放着所有isapi?filter的文件名，iis服务器启动时从该键值中获得?
filter的文件名并加载它们。?

hkey_local_machine/system/currentcontrolset/services/w3svc/parameters/filterdll?

2、然后服务器调用每个filter提供的getfilterversion(?)函数，获得版本号以及该filter希望处理的事件，即isapi?filter通过引出getfilterversion(?)函数来告知服务器自己希望处理什么类型的事件，因为isapi?filter是通过事件来激活的，当满足条件的事件到达时，服务器就会调用filter引出的主函数httpfilterproc(?)对该事件进行处理。getfilterversion(?)的原型如下：?

bool?winapi?getfilterversion(?
dword?dwserverfilterversion;?//in，服务器使用的版本规范?
dword?dwfilterversion;?//out，过滤器使用的版本规范?
char?lpszfilterdesc[sf_max_filter_desc_len+1];?//out，对该过滤器的描述字符串?
dword?dwflags?//out，事件和优先级标志?
)；?

事件和优先级标志dwflasg的取值在msdn中有详细解释，其中包括该filter被调用的优先级，一般应使用默认的低优先级，否则可能会对系统的性能造成很大影响。?

3、httpfilterproc(?)是isapi?filter主要的入口函数，它根据当前的事件的不同作出不同的处理。服务器通过如下的参数块和filter进行交互，这个参数块的作用和isa中的ecb类似。?

typedef?struct?_http_filter_context?
{?

dword?cbsize;?//in，本参数块的大小?
dword?revision;?//in?
pvoid?servercontext;?//in，由server使用本参数?
dword?ulreserved;?//in，由server使用本参数?
bool?fissecureport;?//in，事件是否发生在安全端口上?
pvoid?pfiltercontext;?//in/out，与本次请求相关的上下文?

//回调函数，取得关于服务器和本次连接的信息?
bool?(winapi?*?getservervariable)?(?
struct?_http_filter_context?*?pfc,?
lpstr?lpszvariablename,?
lpvoid?lpvbuffer,?
lpdword?lpdwsize?
);?

bool?(winapi?*?addresponseheaders)?(?//回调函数，给http响应添加一个标头?
struct?_http_filter_context?*?pfc,?
lpstr?lpszheaders,?
dword?dwreserved?
);?

bool?(winapi?*?writeclient)?(?//回调函数，将原始数据发送给客户端?
struct?_http_filter_context?*?pfc,?
lpvoid?buffer,?
lpdword?lpdwbytes,?
dword?dwreserved?
);?

void?*?(winapi?*?allocmem)?(?//回调函数，分配内存。?
struct?_http_filter_context?*?pfc,?
dword?cbsize,?
dword?dwreserved?
);?

bool?(winapi?*?serversupportfunction)?(?//回调函数，访问服务器的一般和特定功能?
struct?_http_filter_context?*?pfc,?
enum?sf_req_type?sfreq,?
pvoid?pdata,?
dword?ul1,?
dword?ul2?
);?

}?http_filter_context,?*phttp_filter_context;?

四、vc++?6.0中对isapi的支持?

vc++?6.0中定义了5个相关的类以简化isapi的编程工作：chttpserver、chttpservercontext、chttpfilter、chttpfiltercontext、chtmlstream，这5个类都没有父类。其中chttpserver和chttpservercontext主要用来编写isa，chttpfilter和chttpfiltercontext则用来编写isapi?filter，而chtmlstream则用来操作内存中的html文件，为其它的4个类提供服务。chttpserver在每个isa中只能有一个实例，一个chttpserver可以对应多个chttpservercontext实例，每个?
chttpservercontext处理一个客户请求，这样可以处理并发的http请求；cttpfilter和chttpfiltercontext之间的关系与此类似，在每个isapi?filter中只能有一个chttpfilter实例，但是可以有多个chttpfiltercontext来处理并发的事件。chttpserver和chttpfilter是独立的类，它们可以共存于一个dll中，也可以分别在不同的dll中。?

一个isa可以提供多个命令，每个命令对应于chttpserver（或其子类）的一个成员函数，客户端可以在url中指定命令名及其参数。在vc++?6.0中是通过parse?map来实现这种对应的。?

parse?map类似mfc中的windows消息分发机制，通过使用vc提供的declare_parse_map、begin_parse_map、on_parse_command、on_parse_command_params、default_parse_command、end_parse_map等宏，可以实现对不同的命令的处理。每个chttpserver中只能建立一个parse?map，当客户端给isa发来命令的时候，parse?map可以分析http请求中的命令名及其参数，将该命令与相应的成员函数关联起来，即由该成员函数处理该命令。以msdn中的例子程序pinball为例，该例中有下面这样一个表单：?

?
?
?attack?from?mars
?
?twilight?zone
?
?the?addams?family
?
?cirqus?voltaire
?
?i?don't?see?it?here
?

?
?
?

当客户端选中了上面的表单中的“attack?from?mars”这一项并点击了submit按钮后，服务器端?
最终将得到如下的url串：?

http://www.abc.com/pinball.dll?mfcisapicommand=getimage&favorite=1?

在该url串中，命令名是getimage，参数favorite的值是1，因此pinball.dll中的如下成员函数?
将被调用以处理该请求，其中参数dwchoice对应url中的参数favorite：?

void?cpinballextension::getimage(chttpservercontext*?pctxt,?long?dwchoice)；?

而parse?map需要按照下面的形式定义：?

//cpinballextension从chttpserver派生而来?
begin_parse_map(cpinballextension,?chttpserver)?

//getimage是cpinballextension的成员函数，且有一个long型的参数即dwchoice?
on_parse_command(getimage,?cpinballextension,?its_i4)?

//该参数在url中的名字为favorite?
on_parse_command_params("favorite")?

end_parse_map(cpinballextension)?

而对于isapi?filter，在vc中可以通过重载chttpfilter（或其子类）的不同的成员函数来实现对不同事件的处理。可重载的函数如下，每一个成员函数均对应一个或多个事件：?

onpreprocheaders?
onauthentication?
onurlmap?
onsendrawdata?
onreadrawdata?
onlog?
onendofnetsession?

msdn提供了4个关于isapi的编程实例：counter、mfcucase、pinball、wwwquote，有兴趣的可看看，本文主要不是介绍编程，所以不再赘述。?