HTTP
PUBLISHED
HTTP (Hypertext Transfer Protocol) is a networking protocol for distributed, collaborative hypermedia information systems. It allows applications to connect to a Web server to fetch and transmit a Web resource.
The main features of the HTTP API include:
- HTTP session
A session is a set of 1 or more transactions. You must create an HTTP session before you can create transactions.
- HTTP transaction
A transaction represents a single operation between a client and a server (a single request to the Web server). To request for a resource from a Web server, create a transaction handle and open an HTTP transaction from the HTTP session.
- HTTP request
A request is message sent from a client to a server (for example, a request to fetch a resource from the Web server).
To send a request, set the remote Web server resource path with the
http_transaction_request_set_uri()
function, and submit the request with thehttp_transaction_submit()
function. - HTTP response
A response is a message sent from a server to a client.
Prerequisites
To enable your application to use the HTTP functionality:
-
To use the functions and data types of the HTTP API (in mobile [1] and wearable [2] applications), include the
<http.h>
header file in your application:#include <http.h>
-
Initialize the HTTP functionality using the
http_init()
function:int ret = HTTP_ERROR_NONE; ret = http_init(); if (ret != HTTP_ERROR_NONE) printf("http_init failed: %d", ret);
When no longer needed, deinitialize the HTTP functionality:
int ret = HTTP_ERROR_NONE; ret = http_deinit(); if (ret != HTTP_ERROR_NONE) printf("http_deinit failed: %d", ret);
Managing Sessions
The application can manage multiple sessions at the same time. When creating the session, you can set the session mode:
- The normal mode (
HTTP_SESSION_MODE_NORMAL
) means that the session has only 1 connection. All transactions in the session share that connection, and the transactions are processed one at a time. - The pipelining mode (
HTTP_SESSION_MODE_PIPELINING
) means that multiple transactions can be processed concurrently. This mode can reduce the network latency.
To manage HTTP sessions:
- Create an HTTP session handle with the
http_session_create()
function:int ret = HTTP_ERROR_NONE; http_session_h session = NULL; ret = http_session_create(HTTP_SESSION_MODE_NORMAL, &session); if (ret != HTTP_ERROR_NONE) printf("http_session_create failed: %d", ret);
- Set the auto redirection for the session with the
http_session_set_auto_redirection()
function:
int ret = HTTP_ERROR_NONE; bool auto_redirect = true; ret = http_session_set_auto_redirection(session, auto_redirect); if (ret != HTTP_ERROR_NONE) printf("http_session_set_auto_redirection failed: %d", ret);
- When no longer needed, destroy all transactions and the session:
int ret = HTTP_ERROR_NONE; ret = http_session_destroy_all_transactions(session); if (ret != HTTP_ERROR_NONE) printf("http_session_destroy_all_transactions failed: %d", ret); ret = http_session_destroy(session); if (ret != HTTP_ERROR_NONE) printf("http_session_destroy failed: %d", ret);
Managing Transactions
To manage HTTP transactions:
- Create an HTTP transaction handle with the
http_session_open_transaction()
function and the session handle.The function requires the HTTP method defined by the
http_method_e
enumerator (in mobile [3] and wearable [4] applications) as its first parameter. The main methods are:- GET: The application can retrieve a resource from a remote Web server.
- POST: The application can send data to a Web server.
- PUT: The application can replace all current representations of the Web server resource with the uploaded content.
int ret = HTTP_ERROR_NONE; http_transaction_h transaction = NULL; ret = http_session_open_transaction(session, HTTP_METHOD_GET, &transaction); if (ret != HTTP_ERROR_NONE) printf("http_session_open_transaction failed: %d", ret);
The transaction handle is used to manage the request and response.
- Register transaction callbacks to receive the response and monitor the transaction state:
- Use the
http_transaction_set_received_header_cb()
andhttp_transaction_set_received_body_cb()
functions to register callbacks for fetching the Web server resource header information and the response body. - Use the
http_transaction_set_uploaded_cb()
function to register a callback for the upload status of the remote Web server resource. - Use the
http_transaction_set_completed_cb()
function to register a callback for the completion status of the current transaction. - Use the
http_transaction_set_aborted_cb()
function to register a callback for the failure status of the current transaction.
/* Callback for receiving the response header */ void header_cb(http_transaction_h transaction, char* header, size_t header_len, void* user_data) {} http_transaction_set_received_header_cb(transaction, header_cb, NULL); /* Callback for receiving the response body */ void body_cb(http_transaction_h transaction, char* body, size_t size, size_t nmemb, void* user_data) {} http_transaction_set_received_body_cb(transaction, body_cb, NULL); /* Callback for monitoring data uploads */ void uploaded_cb(http_transaction_h transaction, char* body, int recommended_chunk, void* user_data) {} http_transaction_set_uploaded_cb(transaction, uploaded_cb, NULL); /* Callback for monitoring transaction completions */ void completed_cb(http_transaction_h transaction, char* body, void* user_data) {} http_transaction_set_completed_cb(transaction, completed_cb, NULL); /* Callback for monitoring transaction abortions */ void aborted_cb(http_transaction_h transaction, int reason, void* user_data) {} http_transaction_set_aborted_cb(transaction, aborted_cb, NULL);
- Use the
- Send a request:
- Set the request URI for the transaction:
int ret = HTTP_ERROR_NONE; char uri[1024] = "www.example.com"; ret = http_transaction_request_set_uri(transaction, uri); if (ret != HTTP_ERROR_NONE) printf("http_transaction_request_set_uri failed: %d", ret);
- Set the request method:
int ret = HTTP_ERROR_NONE; http_method_e method = HTTP_METHOD_GET; ret = http_transaction_request_set_method(transaction, method); if (ret != HTTP_ERROR_NONE) printf("http_transaction_request_set_method failed: %d", ret);
- Set the HTTP version of the transaction:
int ret = HTTP_ERROR_NONE; http_version_e version = HTTP_VERSION_1_1; ret = http_transaction_request_set_version(transaction, version); if (ret != HTTP_ERROR_NONE) printf("http_transaction_request_set_version failed: %d", ret);
- Submit the transaction for the defined request URI:
int ret = HTTP_ERROR_NONE; ret = http_transaction_submit(transaction); if (ret != HTTP_ERROR_NONE) printf("http_transaction_submit failed: %d", ret);
- Set the request URI for the transaction:
- The response arrives in the registered response header and response body callbacks.
To retrieve response status details:
- Get the status code of the submitted transaction:
int ret = HTTP_ERROR_NONE; http_status_code_e status_code = -1; ret = http_transaction_response_get_status_code(transaction, &status_code); if (ret != HTTP_ERROR_NONE) printf("http_transaction_response_get_status_code failed: %d", ret);
- Get the status version of the submitted transaction:
int ret = HTTP_ERROR_NONE; http_version_e version = -1; ret = http_transaction_response_get_version(transaction, &version); if (ret != HTTP_ERROR_NONE) printf("http_transaction_response_get_version failed: %d", ret);
- Get the status code of the submitted transaction:
- When no longer needed, destroy the transaction:
int ret = HTTP_ERROR_NONE; ret = http_transaction_destroy(transaction); if (ret != HTTP_ERROR_NONE) printf("http_transaction_destroy failed: %d", ret);
The following example shows the code required for a simple HTTP GET, HTTPS GET, or HTTP POST request:
int ret = HTTP_ERROR_NONE; /* Request URI for HTTP GET */ char uri[1024] = "www.example.com"; /* Request URI for HTTPS GET: char uri[1024] = "https://httpbin.org/get"; Request URI and data for HTTP POST: char uri[1024] = "http://posttestserver.com/post.php"; const char* post_msg = "name=tizen&project=http"; */ ret = http_session_create(HTTP_SESSION_MODE_NORMAL, &session); if (ret != HTTP_ERROR_NONE) printf("http_session_create failed: %d", ret); /* Transaction for HTTP and HTTPS GET */ ret = http_session_open_transaction(session, HTTP_METHOD_GET, &transaction); /* Transaction for HTTP POST: ret = http_session_open_transaction(session, HTTP_METHOD_POST, &transaction); */ if (ret != HTTP_ERROR_NONE) printf("http_session_open_transaction failed: %d", ret); ret = http_transaction_request_set_uri(transaction, uri); if (ret != HTTP_ERROR_NONE) printf("http_transaction_request_set_uri failed: %d", ret); /* Data management for HTTP POST: http_transaction_set_ready_to_write(transaction, TRUE); http_transaction_request_write_body(transaction, post_msg); */ ret = http_transaction_submit(transaction); if (ret != HTTP_ERROR_NONE) printf("http_transaction_submit failed: %d", ret);