Tizen Native API  5.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

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.
int http_transaction_set_tcp_fastopen (http_transaction_h http_transaction, bool enable)
 Sets the flag to allow TCP Fast Open.
int http_transaction_get_tcp_fastopen (http_transaction_h http_transaction, bool *enable)
 Gets the flag to allow TCP Fast Open.

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 http_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_tcp_fastopen ( http_transaction_h  http_transaction,
bool *  enable 
)

Gets the flag to allow TCP Fast Open.

Since :
5.0
Remarks:
TCP Fast Open depends on kernel version.
HTTP_ERROR_NOT_SUPPORTED error will be returned for kernel version less than 3.13.
Parameters:
[in]http_transactionThe HTTP transaction handle
[out]enableThe flag to enable TCP Fast Open
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_tcp_fastopen ( http_transaction_h  http_transaction,
bool  enable 
)

Sets the flag to allow TCP Fast Open.

Since :
5.0
Remarks:
TCP Fast Open depends on kernel version.
HTTP_ERROR_NOT_SUPPORTED error will be returned for kernel version less than 3.13.
Parameters:
[in]http_transactionThe HTTP transaction handle
[in]enableThe flag to enable TCP Fast Open
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