[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。
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:
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。此处不再赘述。