Tizen Native API  6.5

The cion client API provides functions for cion client.

Required Header

#include <cion.h>

Overview

The cion client can request to connect to server and send or receive data. It provides functions to create cion client and communication APIs.

Functions

int cion_client_create (cion_client_h *client, const char *service_name, cion_security_h security)
 Creates a Cion client handle.
int cion_client_destroy (cion_client_h client)
 Destroys the Cion client handle.
int cion_client_try_discovery (cion_client_h client, cion_client_server_discovered_cb cb, void *user_data)
 Tries to discover a Cion server.
int cion_client_stop_discovery (cion_client_h client)
 Stops to discovery Cion server.
int cion_client_connect (cion_client_h client, const cion_peer_info_h peer_info)
 Tries to connect to the Cion server.
int cion_client_disconnect (cion_client_h client)
 Disconnects from a server.
int cion_client_send_data (cion_client_h client, unsigned char *data, unsigned int data_size, int timeout, unsigned char **return_data, unsigned int *return_data_size)
 Sends the data.
int cion_client_send_payload_async (cion_client_h client, cion_payload_h payload, cion_client_payload_async_result_cb cb, void *user_data)
 Sends the payload asynchronously.
int cion_client_add_connection_result_cb (cion_client_h client, cion_client_connection_result_cb cb, void *user_data)
 Adds callback function for connection result.
int cion_client_remove_connection_result_cb (cion_client_h client, cion_client_connection_result_cb cb)
 Removes callback function for connection result.
int cion_client_add_payload_received_cb (cion_client_h client, cion_client_payload_received_cb cb, void *user_data)
 Adds callback function to receive payload.
int cion_client_remove_payload_received_cb (cion_client_h client, cion_client_payload_received_cb cb)
 Removes callback function to receive payload.
int cion_client_add_disconnected_cb (cion_client_h client, cion_client_disconnected_cb cb, void *user_data)
 Adds callback function for disconnection event.
int cion_client_remove_disconnected_cb (cion_client_h client, cion_client_disconnected_cb cb)
 Removes callback function for disconnection event.

Typedefs

typedef void * cion_client_h
 The Cion client handle.
typedef void(* cion_client_server_discovered_cb )(const char *service_name, const cion_peer_info_h peer_info, void *user_data)
 Called when the server is discovered.
typedef void(* cion_client_connection_result_cb )(const char *service_name, const cion_peer_info_h peer_info, const cion_connection_result_h result, void *user_data)
 Called when the connection is accepted or rejected.
typedef void(* cion_client_payload_async_result_cb )(const cion_payload_async_result_h result, void *user_data)
 Called after sending payload asynchronously.
typedef void(* cion_client_payload_received_cb )(const char *service_name, const cion_peer_info_h peer_info, const cion_payload_h payload, cion_payload_transfer_status_e status, void *user_data)
 Called when the payload is received.
typedef void(* cion_client_disconnected_cb )(const char *service_name, const cion_peer_info_h peer_info, void *user_data)
 Called when the connection is disconnected.

Typedef Documentation

typedef void(* cion_client_connection_result_cb)(const char *service_name, const cion_peer_info_h peer_info, const cion_connection_result_h result, void *user_data)

Called when the connection is accepted or rejected.

Since :
6.5
Parameters:
[in]service_nameThe name of service
The service_name can be used only in the callback. To use outside, make a copy.
[in]peer_infoThe Cion peer information handle
The peer_info can be used only in the callback. To use outside, make a copy.
[in]resultThe handle for connection result
The result can be used only in the callback. To use outside, make a copy.
[in]user_dataThe user data
See also:
cion_client_add_connection_result_cb()
cion_peer_info_h
cion_connection_result_h
typedef void(* cion_client_disconnected_cb)(const char *service_name, const cion_peer_info_h peer_info, void *user_data)

Called when the connection is disconnected.

Since :
6.5
Parameters:
[in]service_nameThe name of service
The service_name can be used only in the callback. To use outside, make a copy.
[in]peer_infoThe cion peer information handle
The peer_info can be used only in the callback. To use outside, make a copy.
[in]user_dataThe user data
See also:
cion_client_add_disconnected_cb()
cion_peer_info_h
typedef void* cion_client_h

The Cion client handle.

Since :
6.5
typedef void(* cion_client_payload_async_result_cb)(const cion_payload_async_result_h result, void *user_data)

Called after sending payload asynchronously.

Since :
6.5
Parameters:
[in]resultThe result of sending payload
The result can be used only in the callback. To use outside, make a copy.
[in]user_dataThe user data
See also:
cion_client_send_payload_async()
cion_payload_async_result_h
typedef void(* cion_client_payload_received_cb)(const char *service_name, const cion_peer_info_h peer_info, const cion_payload_h payload, cion_payload_transfer_status_e status, void *user_data)

Called when the payload is received.

Since :
6.5
Parameters:
[in]service_nameThe name of service
The service_name is the name of connected service that sent the payload. The service_name can be used only in the callback. To use outside, make a copy.
[in]peer_infoThe Cion peer information handle
The peer_info can be used only in the callback. To use outside, make a copy.
[in]payloadThe received payload
The payload can be used only in the callback.
The payload should not be released.
[in]statusThe status of transfer
[in]user_dataThe user data
See also:
cion_client_add_payload_received_cb()
cion_peer_info_h
cion_payload_h
cion_payload_transfer_status_e
typedef void(* cion_client_server_discovered_cb)(const char *service_name, const cion_peer_info_h peer_info, void *user_data)

Called when the server is discovered.

Since :
6.5
Parameters:
[in]service_nameThe name of service
The service_name can be used only in the callback. To use outside, make a copy.
[in]peer_infoThe Cion peer information handle
The peer_info can be used only in the callback. To use outside, make a copy.
[in]user_dataThe user data
See also:
cion_client_try_discovery()
cion_peer_info_h

Function Documentation

Adds callback function for connection result.

Since :
6.5
Parameters:
[in]clientThe Cion client handle
[in]cbThe callback function
[in]user_dataThe user data
Returns:
0 on success, otherwise a negative error value
Return values:
CION_ERROR_NONESuccessful
CION_ERROR_INVALID_PARAMETERInvalid parameter
See also:
cion_client_connection_result_cb()
cion_client_remove_connection_result_cb()
Sample code:
#include <cion.h>

{
    int ret;

    ret = cion_client_add_connection_result_cb(client,
            _cion_client_connection_result_cb, NULL);
}
int cion_client_add_disconnected_cb ( cion_client_h  client,
cion_client_disconnected_cb  cb,
void *  user_data 
)

Adds callback function for disconnection event.

Since :
6.5
Parameters:
[in]clientThe Cion client handle
[in]cbThe callback function
[in]user_dataThe user data
Returns:
0 on success, otherwise a negative error value
Return values:
CION_ERROR_NONESuccessful
CION_ERROR_INVALID_PARAMETERInvalid parameter
See also:
cion_client_disconnected_cb()
cion_client_remove_disconnected_cb()
Sample code:
#include <cion.h>

{
    int ret;

    ret = cion_client_add_disconnected_cb(client,
            _cion_client_disconnected_cb, NULL);
}

Adds callback function to receive payload.

Since :
6.5
Parameters:
[in]clientThe Cion client handle
[in]cbThe callback function
[in]user_dataThe user data
Returns:
0 on success, otherwise a negative error value
Return values:
CION_ERROR_NONESuccessful
CION_ERROR_INVALID_PARAMETERInvalid parameter
See also:
cion_client_payload_received_cb()
cion_client_remove_payload_received_cb()
Sample code:
#include <cion.h>

{
    int ret;

    ret = cion_client_add_payload_received_cb(client,
            _cion_client_payload_received_cb, NULL);
}
int cion_client_connect ( cion_client_h  client,
const cion_peer_info_h  peer_info 
)

Tries to connect to the Cion server.

Since :
6.5
Privilege Level:
public
Privilege:
http://tizen.org/privilege/d2d.datasharing
http://tizen.org/privilege/internet
Parameters:
[in]clientThe Cion client handle
[in]peer_infoThe Cion peer information handle
Returns:
0 on success, otherwise a negative error value
Return values:
CION_ERROR_NONESuccessful
CION_ERROR_PERMISSION_DENIEDPermission denied
CION_ERROR_INVALID_PARAMETERInvalid parameter
CION_ERROR_INVALID_OPERATIONInvalid operation
CION_ERROR_IO_ERRORIO error
Sample code:
#include <cion.h>

{
    int ret;

    ret = cion_client_connect(client, peer_info);
}
int cion_client_create ( cion_client_h client,
const char *  service_name,
cion_security_h  security 
)

Creates a Cion client handle.

The Cion client requests connection to server.

Since :
6.5
Remarks:
client must be released using cion_client_destroy().
Max length of service_name including the null terminator is 512.
Parameters:
[out]clientThe Cion client handle
[in]service_nameThe name of service
[in]securityThe Cion security handle
Returns:
0 on success, otherwise a negative error value
Return values:
CION_ERROR_NONESuccessful
CION_ERROR_NOT_SUPPORTEDNot supported
CION_ERROR_INVALID_PARAMETERInvalid parameter
CION_ERROR_OUT_OF_MEMORYOut of memory
CION_ERROR_INVALID_OPERATIONInvalid operation
CION_ERROR_OPERATION_FAILEDOperation failed
See also:
cion_server_destroy()
cion_security_create()
Sample code:
#include <cion.h>

{
    int ret;
    cion_client_h client = NULL;

    ret = cion_client_create(&client, "myclient", NULL);
}

Destroys the Cion client handle.

Since :
6.5
Parameters:
[in]clientThe Cion client handle
Returns:
0 on success, otherwise a negative error value
Return values:
CION_ERROR_NONESuccessful
CION_ERROR_INVALID_PARAMETERInvalid parameter
See also:
cion_security_create()
Sample code:
#include <cion.h>

{
    int ret;

    ret = cion_client_destroy(client);
}

Disconnects from a server.

Since :
6.5
Parameters:
[in]clientThe Cion client handle
Returns:
0 on success, otherwise a negative error value
Return values:
CION_ERROR_NONESuccessful
CION_ERROR_INVALID_PARAMETERInvalid parameter
Sample code:
#include <cion.h>

{
    int ret;

    ret = cion_client_disconnect(client);
}

Removes callback function for connection result.

Since :
6.5
Parameters:
[in]clientThe Cion client handle
[in]cbThe callback function
Returns:
0 on success, otherwise a negative error value
Return values:
CION_ERROR_NONESuccessful
CION_ERROR_INVALID_PARAMETERInvalid parameter
See also:
cion_client_connection_result_cb()
cion_client_add_connection_result_cb()
Sample code:
#include <cion.h>

{
    int ret;

    ret = cion_client_remove_connection_result_cb(client,
            _cion_client_connection_result_cb);
}

Removes callback function for disconnection event.

Since :
6.5
Parameters:
[in]clientThe Cion client handle
[in]cbThe callback function
Returns:
0 on success, otherwise a negative error value
Return values:
CION_ERROR_NONESuccessful
CION_ERROR_INVALID_PARAMETERInvalid parameter
See also:
cion_client_disconnected_cb()
cion_client_add_disconnected_cb()
Sample code:
#include <cion.h>

{
    int ret;

    ret = cion_client_remove_disconnected_cb(client,
            _cion_client_disconnected_cb);
}

Removes callback function to receive payload.

Since :
6.5
Parameters:
[in]clientThe Cion client handle
[in]cbThe callback function
Returns:
0 on success, otherwise a negative error value
Return values:
CION_ERROR_NONESuccessful
CION_ERROR_INVALID_PARAMETERInvalid parameter
See also:
cion_client_payload_received_cb()
cion_client_add_payload_received_cb()
Sample code:
#include <cion.h>

{
    int ret;

    ret = cion_client_remove_payload_received_cb(client,
            _cion_client_payload_received_cb);
}
int cion_client_send_data ( cion_client_h  client,
unsigned char *  data,
unsigned int  data_size,
int  timeout,
unsigned char **  return_data,
unsigned int *  return_data_size 
)

Sends the data.

Since :
6.5
Remarks:
return_data must be released using free().
Parameters:
[in]clientThe Cion client handle
[in]dataThe data to send
[in]data_sizeThe size of data
[in]timeoutThe time(milliseconds) to check time out
[out]return_dataThe returned data
[out]return_data_sizeThe size of returned data
Returns:
0 on success, otherwise a negative error value
Return values:
CION_ERROR_NONESuccessful
CION_ERROR_INVALID_PARAMETERInvalid parameter
CION_ERROR_IO_ERRORIO error
CION_ERROR_TIMED_OUTTimed out
CION_ERROR_INVALID_OPERATIONInvalid operation
CION_ERROR_OUT_OF_MEMORYOut of memory
Sample code:
#include <cion.h>

{
    int ret;
    unsigned char *return_data = NULL,
    unsigned int return_size;

    ret = cion_client_send_data(client, "senddata", 8, 10,
            &return_data, &return_size);
}

Sends the payload asynchronously.

Since :
6.5
Parameters:
[in]clientThe Cion client handle
[in]payloadThe payload handle
[in]cbThe callback function
[in]user_dataThe user data
Returns:
0 on success, otherwise a negative error value
Return values:
CION_ERROR_NONESuccessful
CION_ERROR_INVALID_PARAMETERInvalid parameter
CION_ERROR_INVALID_OPERATIONInvalid Operation
See also:
cion_payload_create()
cion_client_payload_async_result_cb()
Sample code:
#include <cion.h>

{
    int ret;

    ret = cion_client_send_payload_async(client, payload,
            _cion_client_payload_async_result_cb, NULL);
}

Stops to discovery Cion server.

Since :
6.5
Parameters:
[in]clientThe Cion client handle
Returns:
0 on success, otherwise a negative error value
Return values:
CION_ERROR_NONESuccessful
CION_ERROR_INVALID_PARAMETERInvalid parameter
CION_ERROR_INVALID_OPERATIONInvalid
Sample code:
#include <cion.h>

{
    int ret;

    ret = cion_client_stop_discovery(client);
}
int cion_client_try_discovery ( cion_client_h  client,
cion_client_server_discovered_cb  cb,
void *  user_data 
)

Tries to discover a Cion server.

Since :
6.5
Privilege Level:
public
Privilege:
http://tizen.org/privilege/d2d.datasharing
http://tizen.org/privilege/internet
Remarks:
Tries to discover the server with service name that the client handle has.
Parameters:
[in]clientThe Cion client handle
[in]cbThe callback function
[in]user_dataThe user data
Returns:
0 on success, otherwise a negative error value
Return values:
CION_ERROR_NONESuccessful
CION_ERROR_PERMISSION_DENIEDPermission denied
CION_ERROR_INVALID_PARAMETERInvalid parameter
CION_ERROR_ALREADY_IN_PROGRESSAlready in progress
CION_ERROR_IO_ERRORIO error
See also:
cion_client_server_discovered_cb()
Sample code:
#include <cion.h>

{
    int ret;

    ret = cion_client_try_discovery(client,
            _cion_client_server_discovered_cb, NULL);
}