fmpdam1.2协议报文格式说明

简介：

        fmpdam（Fast message pasing Database access middleware－快速数据库访问中间件）协议以HTTP为基础协议建立，请求和响应报文以完全不同的格式组成；请求报文直接使用HTTP中表单格式和多部分表单（MultipartForms）格式。响应部分为自定义流式小端序协议，称为fmpdam协议（或fmpdam响应协议）；请求报文和响应报文中的字符均使用UTF8编码，对于application/x-www-form-urlencoded请求，用户可选择遵循RFC3986之标准对报文主体进行URL编码。下将请求部分称为fmpdam请求，响应称为fmpdam响应；

fmpdam请求：

        fmpdam支持报文主体为application/x-www-form-urlencoded或multipart/form-data类型的POST请求（使用GET请求可得到对应接口文档。不支持除POST、GET之外的请求动词），用户在提交fmpdam请求时需正确设置HTTP请求头中Content-Type首部的值为application/x-www-form-urlencoded或multipart/form-data，并严格按照RFC2616、RFC3986和或RFC2388之标准组织报文主体，对于application/x-www-form-urlencoded报文，格式如下：

key1=value1&key2=value2&keyN=valueN

对于multipart/form-data报文，格式如下（假设Content-Type首部的值为： multipart/form-data;boundary=----WebKitFormBoundaryOog3VnP3TtJqkpUQ）：

------WebKitFormBoundaryOog3VnP3TtJqkpUQ

Content-Disposition:form-data; name ="Args1"

 

Value1

------WebKitFormBoundaryOog3VnP3TtJqkpUQ

Content-Disposition:form-data; name = "Args2"

 

Value2

------WebKitFormBoundaryOog3VnP3TtJqkpUQ

Content-Disposition:form-data; name = "KeyN";

 

ValueN

------WebKitFormBoundaryOog3VnP3TtJqkpU--

上述multipart/form-data内容的16进制对照如下（注意结尾的 2D 2D 0D 0A）：



用户可选择性的对application/x-www-form-urlencoded类型主体按照RFC3986所规定的进行URL编码；但由于&和=符分别用于分隔和识别Key、Value，若Key或Value中出现&或=符，用户必须选择对报文主体进行URL编码，否则将导致报文主体无法被解析产生不可预料后果。

  fmpdam不支持编码的multipart/form-data实体和嵌套实体，不要使用base64等对multipart/form-data实体进行编码。

fmpdam响应：

当HTTP状态码< 200 || >= 300 时，表示响应主体中仅包含一个使用UTF8编码的错误描述字符串；绝大多数时候fmpdam客户代理程序应向客户直接展示该错误描述以提示错误。也可针对HTTP状态码另作处理。

当HTTP状态为200 时 fmpdam响应部分为自定义流式小端序协议，并会使用HTTP Chunked对内容编码（后续可能会对报文进行压缩传输，客户程序不应假设fmpdam协议不使用HTTP的传输编码）；结构描述如下：

协议头部：

       2字节标识（0x80, 0xff）

       2字节版本（低字节主版本，高字节次版本，当前为1.2）

       2字节错误描述串长度（若该值不为零，表示执行语句过程中出现错误，若有语句已执行，则回滚。）注：fmpdam1.1已将此字段删除。

       错误描述字符串注：fmpdam1.1已将此字段删除。

 

协议正文部分：

 

记录集（执行结果）头部：

       2字节语句名称串长度，语句名称字符串

       4字节记录数量（当值为0xffffffff时表示语句不返回结果集，数据中不再包含后续内容）注：fmpdam1.2中记录数量字段的意义有变更。仅当其值为0xffffffff时表示执行的语句不返回结果集，其它的任何值都是无意义的。因为在遍历记录集之前无法得知记录数量，但fmpdam服务必须在发送记录集之前发送该字段，如果仍必须保持此字段有效，则可能导致fmpdam服务遍历记录集两次。

       2字节字段数量（对于不返回结果集的语句，响应包中将不再包含从此开始的数据）

 

字段描述部分：

       1字节字段1类型，1字节字段名称字符长度，字段1名称串\0；1字节字段2类型，1字节字段名称字符长度，字段2名称串\0，1字节字段N类型，1字节字段N名称串长度，字段N名称串\0

注：

       字段名称包含零结尾，客户程序在解析字段信息时可直从接收响应的缓冲区中引用该字段串以便减少资源占用。

记录集部分：

       第一条记录：

              字段1数据，字段2数据，字段N数据

       第N条记录：

              字段1数据，字段2数据，字段N数据

 
注意：

除字符串和二进制外其它类型数据长度固定，Bit、UCHAR为1字节，SHORT为2字节，LONG、FLOAT为4字节，DOUBLE8字节，时间戳8字节（精确到毫秒的Unix timestamp）。字符串和二进制数据开头4字节用于描述字节长度，后随数据。字符串使用ODBC驱动设置的编码（通常设置为UTF8，若用户熟知如何使用fmpdam模块，可自行修改，否则不建议修改）。
该协议无完整性校验机制，当利用HTTP Chunked编码的终止块作完整性校验。

 

fmpdam响应协议结构图解：

2017年11月15日21时41分

付浩

 

修订：

       fmpdam协议升级为1.1版，相较1.0版响应报文中不再包含错误描述部分。语义升级为：如果执行语句过程中出现错误则回滚到执行语句前的状态。

 

2017年11月16日18时20分

付浩

 

       fmpdam协议升级为1.2版，相较1.1版fmpdam1.2 中记录数量字段的意义有变更。仅当其值为0xffffffff时表示执行的语句不返回结果集，其它的任何值都是无意义的。因为在遍历记录集之前无法得知记录数量，但fmpdam服务必须在发送记录集之前发送该字段，如果仍必须保持此字段有效，则可能导致fmpdam服务遍历记录集两次。

 

2017年11月21日18时23分

付浩

 

备注：

       fmpdam 协议以HTTP为基础协议，目前尚未使用HTTP的缓存机制，将来可能会用If-Modified-Since和（或）If-None-Match首部，界时，fmpdam服务可能返回（HTTP的）304状态。所以，建议设计客户端时酌情处理If-Modified-Since和（或）If-None-Match首部以及304状态；