[FAQ00167] [OBIGO]基于WPS的HTTP编程介绍

[FAQ00167] [OBIGO]基于WPS的HTTP编程介绍

Download

Platform: MT6235MT6236MT6250MT6252...

Branch: 10AW1032MP10AW1108MP10AW1116MP11AW1112MP...

FAQ Content [description]   MTK有没有提供HTTP编程的接口，如何使用？   [solution]   Introduction for WPS WPS is a adaption layer for internet application to access HTTP service。It can provide service including WAP/WTLS/HTTP/HTTPS。It is only a name of module developed by MTK, please don’t consider it as a protocol name. Comparing with Socket, network coding based on WPS is very easy. It is no need for developers to have knowledge on WAP/HTTP protocol. Therefore, you can focus on your application best. Interface between WPS and application are primitives.  Architecture of communication between application and WPS： Below is the step of coding: 1、 Init profile setting：including registering app id for the application, setting the parameters such as apn、proxy and so on ； 2、 Setup a channel； 3、 Send HTTP request； 4、 Receive the reply； 5、 Remove the channel。   Main related structures and Enum wps_set_channel_req_struct; (This struct will be packaged in local parameter of set channel request) typedef struct {     kal_uint8 ref_count;     kal_uint16 msg_len;        kal_bool use_default;      kal_uint8 conn_type;     kal_uint32 req_id;     kal_uint32 net_id;      kal_uint32 timeout;     kal_bool use_proxy;      kal_uint8 prx_ip[4]; // proxy address     kal_uint16 prx_port; // proxy port     kal_uint8 username[30];     kal_uint8 password[30];     kal_uint8 server_auth_username[WPS_MAX_AUTH_USERNAME_LENGTH];     kal_uint8 server_auth_password[WPS_MAX_AUTH_PASSWORD_LENGTH];      kal_uint8 app_id; } wps_set_channel_req_struct; Description for important parameters: Parameter Description use_default If you want to use active profile of browser, please set it true. conn_type Protocol you want to use, ex. WPS_CONN_HTTP, WPS_CONN_WSP_CO, etc net_id encoded data account id with function: cbm_encode_data_account_id timeout How long you want to wait if there is no response from network. If time out, request will be canceled. use_proxy Whether use proxy or not. prx_ip[4] proxy address prx_port proxy port username proxy authentication, user name if needed. Ascii with ‘0’ as terminator. password proxy authentication, password if needed. Ascii with ‘0’ as terminator. server_auth_username server authentication. Ascii with ‘0’ as terminator. server_auth_password server authentication. Ascii with ‘0’ as terminator. app_id Get by calling cbm_register_app_id.   wps_set_channel_req_var_struct (this struct will be packaged in peer buffer of set channel request) typedef struct {     kal_uint32 static_header_len;     kal_uint8* static_header; } wps_set_channel_req_var_struct; Description for important parameters: Parameter Description static_header General http header. Including “accept”, “accept language”, “UA”, etc.   wps_set_channel_rsp_struct (this struct will be packaged into local parameter) typedef struct {     kal_uint8 ref_count;     kal_uint16 msg_len;        kal_uint8 channel_id;     kal_uint8 result;     kal_uint32 req_id; } wps_set_channel_rsp_struct; Decription for important parameters: Parameter Description channel_id Identifier of channel, it is allocated by WPS. APP should use it when send a request. result Indicate whether set channel success or reason of failure. Please refer to WPS_RESULT_ERROR_ENUM   wps_http_req_struct  (this struct will be packaged into local parameter) typedef struct {     kal_uint8 ref_count;     kal_uint16 msg_len;        kal_uint8 channel_id;        kal_uint8 request_id;     kal_uint8 method;     kal_uint32 option;     kal_uint8 reply_type;     kal_wchar reply_path[256];     kal_uint32 reply_segment_len;     kal_uint8 post_type;     kal_wchar post_path[256];     kal_uint32 post_total_len;     kal_bool   more_post; } wps_http_req_struct;  Decription for important parameters: Parameter Description channel_id Channel id returned from WPS request_id It should be maintained by application method HTTP method, ex: get(0x40), post(0x60). option Options for http stack. Ex. WPS_HTTP_OPTION_NO_CACHE. Please refer to Wps_struct.h. reply_type In which type WPS can be used to transfer data to application. Ex: buffer, file. Please refer to wps_data_type_enum. reply_path Path of reply file if reply_type is WPS_DATA_TYPE_FILE. reply_segment_len Size of segment for WPS to send reply data to app. If reply_type is buffer, please don’t set it larger than the maximum size of control buffer. post_type Type for application to transfer data to WPS if method is “post”. Please refer to wps_data_type_enum. post_path Path of file if post_type is WPS_DATA_TYPE_FILE. post_total_len Content-length of posting data. more_post If there exists rest post data in application, this variable will be true.   wps_http_req_var_struct (this struct will be packaged into peer buffer) typedef struct {     kal_uint32 request_url_len;     kal_uint8* request_url;     kal_uint32 request_header_len;     kal_uint8* request_header;     kal_uint32 post_segment_len;     kal_uint8* post_segment; } wps_http_req_var_struct;   wps_http_rsp_struct (this struct will be packaged into local parameter) typedef struct {     kal_uint8 ref_count;     kal_uint16 msg_len;       kal_uint8 request_id;     kal_uint8 result;     kal_uint16 status;          kal_int32 cause;     kal_uint8 protocol;     kal_uint8 content_type[256];     kal_uint32 content_length;     kal_bool more; } wps_http_rsp_struct; Description for important parameters: Parameter Description result Result of http request response, please refer to wps_result_error_enum status HTTP status code. Ex. 200(ok), 302(found), 404(bad request), etc. cause Detail error cause if result is not WPS_OK, it is used for MTK. protocol Protocol the http reply used. Ex. WPS_PROTOCOL_HTTP. Please refer to wps_struct.h content_type MIME of content, like text/html. content-length Length in bytes of content. more If http reply has been not sent done, it will true. And application must sent MSG_ID_WPS_READ_CONTENT_REQ to read the rest data.   wps_http_rsp_var_struct (this struct will be packaged into peer buffer) typedef struct {     kal_uint32 new_url_len;     kal_uint8* new_url;     kal_uint32 reply_header_len;     kal_uint8* reply_header;     kal_uint32 reply_segment_len;     kal_uint8* reply_segment; } wps_http_rsp_var_struct; Description for important parameters: Parameter Description new_url URL give by server after redirections, if no redirection, it is NULL. reply_header Headers of HTTP reply. reply_segment Content segment of HTTP reply.   wps_read_content_req_struct  (this struct will be packaged into local parameter) typedef struct {     kal_uint8 ref_count;     kal_uint16 msg_len;        kal_uint8 channel_id;     kal_uint8 request_id;     kal_uint8 seq_num;     kal_uint32 read_segment_len; } wps_read_content_req_struct; Description for important parameters: Parameter Description channel_id Channel id associated with the HTTP request request_id Request id associated with the HTTP request seq_num Identifier of every segment if http reply can’t be transfer in one message.   wps_read_content_rsp_struct (this struct will be packaged into local parameter) typedef struct {     kal_uint8 ref_count;     kal_uint16 msg_len;        kal_uint8 request_id;     kal_uint8 seq_num;     kal_uint8 result;     kal_bool more; } wps_read_content_rsp_struct; Description for important parameters: Parameter Description seq_num Since post content was divided into some segments, this variable is identifier of each segment. result Result of reading content response, please refer to wps_result_error_enum more If there is still more data to post or not.   wps_read_content_rsp_var_struct (this struct will be packaged into peer buffer) typedef struct {     kal_uint32 reply_segment_len;     kal_uint8* reply_segment; } wps_read_content_rsp_var_struct; Description for important parameters: Parameter Description reply_segment Content segment of http reply, please merge it with other segment to retrieve the completely http reply.   wps_post_content_res_struct (this struct will be packaged into local parameter) typedef struct {     kal_uint8 ref_count;     kal_uint16 msg_len;        kal_uint8 channel_id;     kal_uint8 request_id;     kal_uint8 seq_num;     kal_bool more; } wps_post_content_res_struct; Description for important parameters: Parameter Description seq_num Since post content was divided into some segments, this variable is identifier of each segment. more If there is still more data to post or not. wps_post_content_res_var_struct (this struct will be packaged into peer buffer) typedef struct {     kal_uint32 post_segment_len;     kal_uint8* post_segment; } wps_post_content_res_var_struct; wps_post_content_ind_struct (this struct will be packaged into local parameter) typedef struct {     kal_uint8 ref_count;     kal_uint16 msg_len;        kal_uint8 request_id;     kal_uint8 seq_num;     kal_uint8 result; } wps_post_content_ind_struct; Description for important parameters: Parameter Description seq_num Since post content was divided into some segments, this variable is identifier of each segment. result Result of cancel request response, please refer to wps_result_error_enum   wps_unset_channel_req_struct (this struct will be packaged into local parameter) typedef struct {     kal_uint8 ref_count;     kal_uint16 msg_len;        kal_uint8 channel_id; } wps_unset_channel_req_struct;   wps_unset_channel_rsp_struct (this struct will be packaged into local parameter) typedef struct {     kal_uint8 ref_count;     kal_uint16 msg_len;        kal_uint8 channel_id;     kal_uint8 result; } wps_unset_channel_rsp_struct; Description for important parameters: Parameter Description result Result of cancel request response, please refer to wps_result_error_enum   wps_cancel_req_struct (this struct will be packaged into local parameter) typedef struct {     kal_uint8 ref_count;     kal_uint16 msg_len;       kal_uint8 channel_id;      kal_uint8 request_id; } wps_cancel_req_struct;   wps_cancel_rsp_struct (this struct will be packaged into local parameter) typedef struct {     kal_uint8 ref_count;     kal_uint16 msg_len;        kal_uint8 request_id;     kal_uint8 result; } wps_cancel_rsp_struct; Description for important parameters: Parameter Description result Result of cancel request response, please refer to wps_result_error_enum wps_clear_req_struct (this struct will be packaged into local parameter) typedef struct {     kal_uint8 ref_count;     kal_uint16 msg_len;     kal_uint8 channel_id;     kal_uint16 request_id;     kal_uint8 operation; }wps_clear_req_struct; Description for important parameters: Parameter Description result Result of cancel request response, please refer to wps_result_error_enum wps_clear_req_var_struct  (this struct will be packaged into peer buffer) typedef struct {    Kal_uint32 cache_url_len;    Kal_uint8 *cache_url; }wps_clear_req_var_struct; Description for important parameters: Parameter Description cache_url If you want clear cache, this parameter must be present. WPS will clear the cache that match the url with given operation. Main related messages Message Name Description Direction MSG_ID_WPS_SET_CHANNEL_REQ Using this primitive to set a new channel. APP->WPS MSG_ID_WPS_SET_CHANNEL_RSP Using this primitive to handle setting channel response WPS->APP MSG_ID_WPS_UNSET_CHANNEL_REQ Unset a existed channel APP->WPS MSG_ID_WPS_UNSET_CHANNEL_RSP Handle unset channel response WPS->APP MSG_ID_WPS_HTTP_REQ Send a HTTP request base on a existed channel APP->WPS MSG_ID_WPS_HTTP_RSP Handle HTTP response message WPS->APP MSG_ID_WPS_READ_CONTENT_REQ If there are more data for a http response, application should use this primitive to read the rest data APP->WPS MSG_ID_WPS_READ_CONTENT_RSP Carried http response data from WPS WPS->APP MSG_ID_WPS_POST_CONTENT_IND For POST method, post data may be not able to send done via MSG_ID_WPS_HTTP_REQ, So WPS send this primitive to indicate he is ready to receive the rest POST data. WPS->APP MSG_ID_WPS_POST_CONTENT_RES APP send POST data APP->WPS MSG_ID_WPS_CANCEL_REQ APP can send this primitive to cancel a existing request before receiving HTTP RSP APP->WPS MSG_ID_WPS_CANCEL_RSP Cancel request response WPS->APP MSG_ID_WPS_CLEAR_REQ Clear cache, auth or cookies using it APP->WPS MSG_ID_WPS_CLEAR_RSP Response for clear request WPS->APP MSG_ID_WPS_RECONFIG_CHANNEL_REQ Remove the channel identified by the given channel id, and setup a new channel using this id with new parameters APP->WPS MSG_ID_WPS_RECONFIG_CHANNEL_RSP Response for reconfigure channel WPS->APP MSG_ID_WPS_RELEASE_ALL_REQ Application can cancel all request and remove all channel set by them APP->WPS MSG_ID_WPS_RELEASE_ALL_RSP Response for release all request WPS->APP Some notes for WPS coding Mandatory: 1) Don’t setup same channels. When and only when values of conn_type, net_id, time_out, use_proxy, prx_ip, prx_port,user_name, password, server_auth_username, server_auth_password or app_id are needed to be changed, you need to setup a new channel. Otherwise, please use the existed channel to send request. 2) Channel id is allocated and maintained by WPS. In http request, you can only use the channel id returned by setup channel response. If you write a not exists channel id in request, a http request response will be received immediately with error invalid channel id. Recommend: 1) Request id is allocated and maintained by application. The request id is identifier of http request, please allocate and maintain it in your application. 2) Don’t setup too many channels at the same time. The maximum channel of system is 4, so you should limit the number of channels at the same time. 3) Should unset channel if not use in a long time. Because the maximum channel is 4, so you should release the channel resources if no request need to be sent in a short time. 4) Don’t set use_default as true if you want to use your own parameter of channel but not the active one of browser. 5) No need to cancel the request which application has received http response of it. Debug notes: If you are facing problems when using WPS, please help to record a catcher log for MTK. The filter is: Enable (PS) WAP OVER GPRS in default filter list; enable MOD_WAP (all class on), MOD_WPS (all class on) in filter list. 对于实例代码部分，由于在每个工程中都有一个.c文件sample_wps.c，请参考此文件中的code。此处不再赘述。