Tizen Native API  4.0
HTTP Transaction

The HTTP Transaction API provides functions for managing HTTP transactions.

Required Header

#include <http.h>

Overview

It allows managing HTTP transactions. Using the HTTP transaction, you can implement features that allow the users of your application to:

  • Open/Close transactions
  • Pause/Resume transaction
  • Transfer HTTP request
  • Get/Set transaction options such as interface, verification and timeout

Related Features

This API is related with the following features:

  • http://tizen.org/feature/network.internet
    It is recommended to design feature related codes in your application for reliability.
    You can check if a device supports the related features for this API by using System Information, thereby controlling the procedure of your application.
    To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.
    More details on featuring your application can be found from Feature Element.

Functions

int http_transaction_submit (http_transaction_h http_transaction)
 Submits the HTTP request.
int http_transaction_destroy (http_transaction_h http_transaction)
 Closes the HTTP transaction handle.
int http_transaction_set_received_header_cb (http_transaction_h http_transaction, http_transaction_header_cb header_cb, void *user_data)
 Registers callback called when receives header.
int http_transaction_set_received_body_cb (http_transaction_h http_transaction, http_transaction_body_cb body_cb, void *user_data)
 Registers callback called when receives body.
int http_transaction_set_uploaded_cb (http_transaction_h http_transaction, http_transaction_write_cb write_cb, void *user_data)
 Registers callback called when writes data.
int http_transaction_set_completed_cb (http_transaction_h http_transaction, http_transaction_completed_cb completed_cb, void *user_data)
 Registers callback called when transaction is completed.
int http_transaction_set_aborted_cb (http_transaction_h http_transaction, http_transaction_aborted_cb aborted_cb, void *user_data)
 Registers callback called when transaction is aborted.
int http_transaction_set_progress_cb (http_transaction_h http_transaction, http_transaction_progress_cb progress_cb, void *user_data)
 Registers the progress callbacks.
int http_transaction_set_timeout (http_transaction_h http_transaction, int timeout)
 Sets the timeout in seconds that is the timeout for waiting the transaction.
int http_transaction_get_timeout (http_transaction_h http_transaction, int *timeout)
 Gets the timeout in seconds for the transaction.
int http_transaction_resume (http_transaction_h http_transaction)
 Resumes the transaction.
int http_transaction_pause (http_transaction_h http_transaction, http_pause_type_e pause_type)
 Pauses the transaction.
int http_transaction_cancel (http_transaction_h http_transaction)
 Cancels the transaction.
int http_transaction_set_ready_to_write (http_transaction_h http_transaction, bool read_to_write)
 Sets ready to write event for a transaction.
int http_transaction_set_interface_name (http_transaction_h http_transaction, const char *interface_name)
 Sets the interface name.
int http_transaction_get_interface_name (http_transaction_h http_transaction, char **interface_name)
 Gets the interface name.
int http_transaction_set_server_certificate_verification (http_transaction_h http_transaction, bool verify)
 Sets the flag to verify a server certificate.
int http_transaction_get_server_certificate_verification (http_transaction_h http_transaction, bool *verify)
 Gets the flag to verify a server certificate.

Function Documentation

int http_transaction_cancel ( http_transaction_h  http_transaction)

Cancels the transaction.

This function cancels the transaction.
The aborted callback is invoked after using it.

Since :
3.0
Parameters:
[in]http_transactionThe HTTP transaction handle
Returns:
0 on success, otherwise negative error value
Return values:
HTTP_ERROR_NONESuccessful
HTTP_ERROR_INVALID_PARAMETERInvalid parameter
HTTP_ERROR_INVALID_OPERATIONInvalid operation
HTTP_ERROR_OPERATION_FAILEDOperation failed
HTTP_ERROR_NOT_SUPPORTEDNot Supported
int http_transaction_destroy ( http_transaction_h  http_transaction)

Closes the HTTP transaction handle.

Since :
3.0
Remarks:
The transaction is released by http_transaction_destroy(). http_transaction should be set to NULL after using it.
Parameters:
[in]http_transactionThe HTTP transaction handle
Returns:
0 on success, otherwise negative error value
Return values:
HTTP_ERROR_NONESuccessful
HTTP_ERROR_INVALID_PARAMETERInvalid parameter
HTTP_ERROR_INVALID_OPERATIONInvalid operation
HTTP_ERROR_NOT_SUPPORTEDNot Supported
See also:
http_transaction_create()
int http_transaction_get_interface_name ( http_transaction_h  http_transaction,
char **  interface_name 
)

Gets the interface name.

Since :
3.0
Remarks:
The interface_name should be freed using free().
Parameters:
[in]http_transactionThe HTTP transaction handle
[out]interface_nameThe interface name
Returns:
0 on success, otherwise negative error value
Return values:
HTTP_ERROR_NONESuccessful
HTTP_ERROR_INVALID_PARAMETERInvalid parameter
HTTP_ERROR_INVALID_OPERATIONInvalid operation
HTTP_ERROR_NOT_SUPPORTEDNot Supported
int http_transaction_get_server_certificate_verification ( http_transaction_h  http_transaction,
bool *  verify 
)

Gets the flag to verify a server certificate.

Since :
3.0
Parameters:
[in]http_transactionThe HTTP transaction handle
[out]verifyThe flag to verify a server certificate; true means verifies; false means it doesn't.
Returns:
0 on success, otherwise negative error value
Return values:
HTTP_ERROR_NONESuccessful
HTTP_ERROR_INVALID_PARAMETERInvalid parameter
HTTP_ERROR_INVALID_OPERATIONInvalid operation
HTTP_ERROR_NOT_SUPPORTEDNot Supported
int http_transaction_get_timeout ( http_transaction_h  http_transaction,
int *  timeout 
)

Gets the timeout in seconds for the transaction.

Since :
3.0
Parameters:
[in]http_transactionThe HTTP transaction handle
[out]timeoutThe timeout in seconds
Returns:
0 on success, otherwise negative error value
Return values:
HTTP_ERROR_NONESuccessful
HTTP_ERROR_INVALID_PARAMETERInvalid parameter
HTTP_ERROR_INVALID_OPERATIONInvalid operation
HTTP_ERROR_NOT_SUPPORTEDNot Supported
int http_transaction_pause ( http_transaction_h  http_transaction,
http_pause_type_e  pause_type 
)

Pauses the transaction.

Since :
3.0
Parameters:
[in]http_transactionThe HTTP transaction handle
[in]pause_typeThe pause type of the connection
Returns:
0 on success, otherwise negative error value
Return values:
HTTP_ERROR_NONESuccessful
HTTP_ERROR_INVALID_PARAMETERInvalid parameter
HTTP_ERROR_INVALID_OPERATIONInvalid operation
HTTP_ERROR_OPERATION_FAILEDOperation failed
HTTP_ERROR_NOT_SUPPORTEDNot Supported
int http_transaction_resume ( http_transaction_h  http_transaction)

Resumes the transaction.

Since :
3.0
Parameters:
[in]http_transactionThe HTTP transaction handle
Returns:
0 on success, otherwise negative error value
Return values:
HTTP_ERROR_NONESuccessful
HTTP_ERROR_INVALID_PARAMETERInvalid parameter
HTTP_ERROR_INVALID_OPERATIONInvalid operation
HTTP_ERROR_OPERATION_FAILEDOperation failed
HTTP_ERROR_NOT_SUPPORTEDNot Supported
int http_transaction_set_aborted_cb ( http_transaction_h  http_transaction,
http_transaction_aborted_cb  aborted_cb,
void *  user_data 
)

Registers callback called when transaction is aborted.

Since :
3.0
Parameters:
[in]http_transactionThe HTTP transaction handle
[in]aborted_cbThe callback function to be called
[in]user_dataThe user data passed to the callback function
Returns:
0 on success, otherwise negative error value
Return values:
HTTP_ERROR_NONESuccessful
HTTP_ERROR_INVALID_PARAMETERInvalid parameter
HTTP_ERROR_INVALID_OPERATIONInvalid operation
HTTP_ERROR_NOT_SUPPORTEDNot Supported
int http_transaction_set_completed_cb ( http_transaction_h  http_transaction,
http_transaction_completed_cb  completed_cb,
void *  user_data 
)

Registers callback called when transaction is completed.

Since :
3.0
Parameters:
[in]http_transactionThe HTTP transaction handle
[in]completed_cbThe callback function to be called
[in]user_dataThe user data passed to the callback function
Returns:
0 on success, otherwise negative error value
Return values:
HTTP_ERROR_NONESuccessful
HTTP_ERROR_INVALID_PARAMETERInvalid parameter
HTTP_ERROR_INVALID_OPERATIONInvalid operation
HTTP_ERROR_NOT_SUPPORTEDNot Supported
int http_transaction_set_interface_name ( http_transaction_h  http_transaction,
const char *  interface_name 
)

Sets the interface name.

Since :
3.0
Parameters:
[in]http_transactionThe HTTP transaction handle
[in]interface_nameThe interface name to use as outgoing network interface
Returns:
0 on success, otherwise negative error value
Return values:
HTTP_ERROR_NONESuccessful
HTTP_ERROR_INVALID_PARAMETERInvalid parameter
HTTP_ERROR_INVALID_OPERATIONInvalid operation
HTTP_ERROR_NOT_SUPPORTEDNot Supported
int http_transaction_set_progress_cb ( http_transaction_h  http_transaction,
http_transaction_progress_cb  progress_cb,
void *  user_data 
)

Registers the progress callbacks.

Registers callback that is called when data is uploaded/downloaded.

Since :
3.0
Parameters:
[in]http_transactionThe HTTP transaction handle
[in]progress_cbThe callback function to be called
[in]user_dataThe user data passed to the callback function
Returns:
0 on success, otherwise negative error value
Return values:
HTTP_ERROR_NONESuccessful
HTTP_ERROR_INVALID_PARAMETERInvalid parameter
HTTP_ERROR_INVALID_OPERATIONInvalid operation
HTTP_ERROR_NOT_SUPPORTEDNot Supported
int http_transaction_set_ready_to_write ( http_transaction_h  http_transaction,
bool  read_to_write 
)

Sets ready to write event for a transaction.

Since :
3.0
Parameters:
[in]http_transactionThe HTTP transaction handle
[out]read_to_writeEnable/disable ready to write
Returns:
0 on success, otherwise negative error value
Return values:
HTTP_ERROR_NONESuccessful
HTTP_ERROR_INVALID_PARAMETERInvalid parameter
HTTP_ERROR_INVALID_OPERATIONInvalid operation
HTTP_ERROR_NOT_SUPPORTEDNot Supported
int http_transaction_set_received_body_cb ( http_transaction_h  http_transaction,
http_transaction_body_cb  body_cb,
void *  user_data 
)

Registers callback called when receives body.

Since :
3.0
Parameters:
[in]http_transactionThe HTTP transaction handle
[in]body_cbThe callback function to be called
[in]user_dataThe user data passed to the callback function
Returns:
0 on success, otherwise negative error value
Return values:
HTTP_ERROR_NONESuccessful
HTTP_ERROR_INVALID_PARAMETERInvalid parameter
HTTP_ERROR_INVALID_OPERATIONInvalid operation
HTTP_ERROR_NOT_SUPPORTEDNot Supported
int http_transaction_set_received_header_cb ( http_transaction_h  http_transaction,
http_transaction_header_cb  header_cb,
void *  user_data 
)

Registers callback called when receives header.

Since :
3.0
Parameters:
[in]http_transactionThe HTTP transaction handle
[in]header_cbThe callback function to be called
[in]user_dataThe user data passed to the callback function
Returns:
0 on success, otherwise negative error value
Return values:
HTTP_ERROR_NONESuccessful
HTTP_ERROR_INVALID_PARAMETERInvalid parameter
HTTP_ERROR_INVALID_OPERATIONInvalid operation
HTTP_ERROR_NOT_SUPPORTEDNot Supported
int http_transaction_set_server_certificate_verification ( http_transaction_h  http_transaction,
bool  verify 
)

Sets the flag to verify a server certificate.

The verify determines whether verifies the peer's certificate.

Since :
3.0
Parameters:
[in]http_transactionThe HTTP transaction handle
[in]verifyThe flag to verify a server certificate; true means verifies; false means it doesn't.
Returns:
0 on success, otherwise negative error value
Return values:
HTTP_ERROR_NONESuccessful
HTTP_ERROR_INVALID_PARAMETERInvalid parameter
HTTP_ERROR_INVALID_OPERATIONInvalid operation
HTTP_ERROR_NOT_SUPPORTEDNot Supported
int http_transaction_set_timeout ( http_transaction_h  http_transaction,
int  timeout 
)

Sets the timeout in seconds that is the timeout for waiting the transaction.

Sets the timeout in seconds that is the timeout for waiting the transaction.
A timeout value of zero means an infinite timeout.

Since :
3.0
Parameters:
[in]http_transactionThe HTTP transaction handle
[in]timeoutThe timeout in seconds
Returns:
0 on success, otherwise negative error value
Return values:
HTTP_ERROR_NONESuccessful
HTTP_ERROR_INVALID_PARAMETERInvalid parameter
HTTP_ERROR_INVALID_OPERATIONInvalid operation
HTTP_ERROR_NOT_SUPPORTEDNot Supported
int http_transaction_set_uploaded_cb ( http_transaction_h  http_transaction,
http_transaction_write_cb  write_cb,
void *  user_data 
)

Registers callback called when writes data.

Since :
3.0
Parameters:
[in]http_transactionThe HTTP transaction handle
[in]write_cbThe callback function to be called
[in]user_dataThe user data passed to the callback function
Returns:
0 on success, otherwise negative error value
Return values:
HTTP_ERROR_NONESuccessful
HTTP_ERROR_INVALID_PARAMETERInvalid parameter
HTTP_ERROR_INVALID_OPERATIONInvalid operation
HTTP_ERROR_NOT_SUPPORTEDNot Supported
int http_transaction_submit ( http_transaction_h  http_transaction)

Submits the HTTP request.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/internet
http://tizen.org/privilege/network.get
Parameters:
[in]http_transactionThe HTTP transaction handle
Returns:
0 on success, otherwise negative error value
Return values:
HTTP_ERROR_NONESuccessful
HTTP_ERROR_INVALID_PARAMETERInvalid parameter
HTTP_ERROR_INVALID_OPERATIONInvalid operation
HTTP_ERROR_NOT_SUPPORTEDNot Supported
HTTP_ERROR_PERMISSION_DENIEDPermission denied