HTTP/2 connection-IoT Platform (Deprecated)(IoT)-阿里云帮助中心

This topic describes the APIs for connecting a device to IoT Platform over the HTTP/2 protocol using the C Link software development kit (SDK).

IOT_HTTP2_Connect

API prototype

void *IOT_HTTP2_Connect(device_conn_info_t *conn_info, http2_stream_cb_t *user_cb)

Description
This API establishes an HTTP/2 connection to IoT Platform using the parameters specified in `conn_info`. You must explicitly call this API in both the Basic Edition and Premium Edition of the SDK.
Parameters
Parameter
Data type
Direction
Description
conn_info
device_conn_info_t *
Input
The connection parameters.
user_cb
http2_stream_cb_t *
Input
This is the callback function for the user registration event.

Additional parameter details

typedef struct {
    char  *product_key;
    char  *device_name;
    char  *device_secret;
    char  *url;
    int   port;
} device_conn_info_t;

Parameter	Description
product_key	Device authentication information. The ProductKey.
device_name	Device authentication information. The device name.
device_secret	Device authentication information. The device secret.
url	The cloud server address.
port	The cloud server port.

typedef struct {
    on_stream_header_callback       on_stream_header_cb;
    on_stream_chunk_recv_callback   on_stream_chunk_recv_cb;
    on_stream_close_callback        on_stream_close_cb;
    on_stream_frame_send_callback   on_stream_frame_send_cb;
    on_stream_frame_recv_callback   on_stream_frame_recv_cb;
    on_reconnect_callback           on_reconnect_cb;
    on_disconnect_callback          on_disconnect_cb;
} http2_stream_cb_t;

Parameter	Description
on_stream_header_cb	The callback function that is invoked when a downstream header is received.
on_stream_chunk_recv_cb	The callback function that is invoked when downstream data is received.
on_stream_close_cb	The callback function that is invoked when a stream is closed.
on_stream_frame_send_cb	The callback function that is invoked when a frame is sent.
on_stream_frame_recv_cb	The callback function that is invoked when a frame is received.
on_reconnect_cb	The callback function for reconnection.
on_disconnect_cb	The callback function for disconnection.

Return values
Value
Description
Not NULL
Success
NULL
Failure

IOT_HTTP2_Stream_Open

API prototype

int IOT_HTTP2_Stream_Open(void *handle, stream_data_info_t *info, header_ext_info_t *header)

Description
This API opens a stream channel based on the connection handle and input parameters. After the channel is opened, you can upload or download streams. You must explicitly call this API in both the Basic Edition and Premium Edition of the SDK.

Parameters

Parameter	Data type	Direction	Description
handle	void *	Input	The connection handle.
info	stream_data_info_t *	Input/Output	The stream operation parameters.
header	header_ext_info_t *	Input	The custom header file. This can be NULL.

Additional parameter details

typedef struct {
    char                *stream;
    uint32_t            stream_len;
    uint32_t            send_len;
    uint32_t            packet_len;
    const char          *identify;
    int                 h2_stream_id;
    char                *channel_id;
    void                *user_data;
} stream_data_info_t;

Parameter	Description
stream	Input parameter. The pointer to the current data stream. It must point to the data segment to be sent. Valid for upstream sending.
stream_len	Input parameter. The length of the entire data stream. Valid for upstream sending.
send_len	Output parameter. The length of the data that has been sent. Valid for upstream sending.
packet_len	Input parameter. The length of a single transmission. Valid for upstream sending.
identify	Input parameter. The server-side stream identifier.
h2_stream_id	Output parameter. The `http2 stream_id` that corresponds to the current transmission.
channel_id	Output parameter. The service channel ID returned by the Open operation.
user_data	Input parameter. The user data passed to the callback function. You can use this to identify the source of the callback.

typedef struct {
    http2_header      *nva;
    int               num;
} header_ext_info_t;

Parameter	Description
nva	The set of user headers.
num	The number of user headers.

Return values
Value
Description
0
Success
A non-zero value
Failure

IOT_HTTP2_Stream_Send

API prototype

int IOT_HTTP2_Stream_Send(void *handle, stream_data_info_t *info, header_ext_info_t *header);

Description
This API sends data to the specified channel ID. A complete data stream usually consists of one header frame and multiple data frames.
You must explicitly call this API in both the Basic Edition and Premium Edition of the SDK.

Parameters

Parameter	Data type	Direction	Description
handle	void *	Input	The connection handle.
info	stream_data_info_t *	Input/Output	The stream operation parameters.
header	header_ext_info_t *	Input	The custom header file. This can be NULL.

Additional parameter details

typedef struct {
    char                *stream;
    uint32_t            stream_len;
    uint32_t            send_len;
    uint32_t            packet_len;
    const char          *identify;
    int                 h2_stream_id;
    char                *channel_id;
} stream_data_info_t;

Parameter	Description
stream	Input parameter. The pointer to the current data stream. It must point to the data segment to be sent. Valid for upstream sending.
stream_len	Input parameter. The length of the entire data stream. Valid for upstream sending.
send_len	Output parameter. The length of the data that has been sent. Valid for upstream sending.
packet_len	Input parameter. The length of a single transmission. Valid for upstream sending.
identify	Input parameter. The server-side stream identifier.
h2_stream_id	Output parameter. The `http2 stream_id` that corresponds to the current transmission.
channel_id	Output parameter. The service channel ID returned by the Open operation.

typedef struct {
    http2_header      *nva;
    int               num;
} header_ext_info_t;

Parameter	Description
nva	The set of user headers.
num	The number of user headers.

Return values
Value
Description
0
Success
A non-zero value
Failure

IOT_HTTP2_Stream_Query

API prototype

int IOT_HTTP2_Stream_Query(void *handle, stream_data_info_t *info, header_ext_info_t *header)

Description
This API requests downstream data from the specified channel ID. This API is similar to a change tracking API. You are notified of downstream data through the `on_stream_chunk_recv_cb` callback. You must explicitly call this API in both the Basic Edition and Premium Edition of the SDK.

Parameters

Parameter	Data type	Direction	Description
handle	void *	Input	The connection handle.
info	stream_data_info_t *	Input/Output	The stream operation parameters.
header	header_ext_info_t *	Input	The custom header file. This can be NULL.

Additional parameter details

typedef struct {
    char                *stream;
    uint32_t            stream_len;
    uint32_t            send_len;
    uint32_t            packet_len;
    const char          *identify;
    int                 h2_stream_id;
    char                *channel_id;
} stream_data_info_t;

Parameter	Description
stream	Input parameter. The pointer to the current data stream. Not valid for this function.
stream_len	Input parameter. The length of the entire data stream. Not valid for this function.
send_len	Output parameter. The length of the data that has been sent. Not valid for this function.
packet_len	Input parameter. The length of a single transmission. Not valid for this function.
identify	Input parameter. The server-side stream identifier.
h2_stream_id	Output parameter. The `http2 stream_id` assigned for the current transmission.
channel_id	Input parameter. The service channel ID.

typedef struct {
    http2_header      *nva;
    int               num;
} header_ext_info_t;

Parameter	Description
nva	The set of user headers.
num	The number of user headers.

Return values
Value
Description
0
Success
A non-zero value
Failure

IOT_HTTP2_Stream_Close

API prototype

int IOT_HTTP2_Stream_Close(void *handle, stream_data_info_t *info)

Description
This API closes the service stream. You must explicitly call this API in both the Basic Edition and Premium Edition of the SDK.
Parameters
Parameter
Data type
Direction
Description
handle
void *
Input
The connection handle.
info
stream_data_info_t *
Input/Output
The stream operation parameters.

Additional parameter details

typedef struct {
    char                *stream;
    uint32_t            stream_len;
    uint32_t            send_len;
    uint32_t            packet_len;
    const char          *identify;
    int                 h2_stream_id;
    char                *channel_id;
} stream_data_info_t;

Parameter	Description
stream	Input parameter. The pointer to the current data stream. Not valid for this function.
stream_len	Input parameter. The length of the entire data stream. Not valid for this function.
send_len	Output parameter. The length of the data that has been sent. Not valid for this function.
packet_len	Input parameter. The length of a single transmission. Not valid for this function.
identify	Input parameter. The server-side stream identifier.
h2_stream_id	Output parameter. The `http2 stream_id` that corresponds to the current transmission. Not valid for this function.
channel_id	Input parameter. The service channel ID.

typedef struct {
    http2_header      *nva;
    int               num;
} header_ext_info_t;

Parameter	Description
nva	The set of user headers.
num	The number of user headers.

Return values
Value
Description
0
Success
A non-zero value
Failure

IOT_HTTP2_Stream_UploadFile

API prototype

int IOT_HTTP2_Stream_UploadFile(void *handle,
                                const char *filename,
                                const char *identify,
                                upload_file_result_cb_t cb,
                                http2_file_upload_opt_t *opt,
                                void *user_data);

Description
This API asynchronously sends a file to a specified stream channel. To use this feature, you must enable the `FEATURE_FS_ENABLE` macro.
You must explicitly call this API in both the Basic Edition and Premium Edition of the SDK.

Parameters

Parameter	Data type	Direction	Description
handle	void *	Input	The connection handle returned when you call the `IOT_HTTP2_Connect` API.
filename	const char *	Input	The file name. The file name can contain only digits `0-9`, letters `a-z` and `A-Z`, underscores `_`, and periods `.`.
identify	const char *	Input	The server-side stream channel identifier. This is fixed to the string `"c/iot/sys/thing/file/upload"`.
cb	upload_file_result_cb	Input	The callback function for the file sending status.
opt	http2_file_upload_opt_t *	Input	The configuration options struct. Currently, only the file overwrite option `UPLOAD_FILE_OPT_BIT_OVERWRITE` is provided.
user_data	void *	Input	The user data passed to the callback function.

Additional parameter details

Callback function prototype

typedef void (* upload_file_result_cb)(const char *path, int result, void *user_data);

Result value range

typedef enum {
    UPLOAD_FILE_NOT_EXIST     = -9, /* The file does not exist. */
    UPLOAD_FILE_READ_FAILED   = -8, /* Failed to read the file. */
    UPLOAD_STREAM_OPEN_FAILED = -7, /* Failed to open the stream. */
    UPLOAD_STREAM_SEND_FAILED = -6, /* Failed to send the stream. */
    UPLOAD_MALLOC_FAILED      = -5, /* Memory allocation failed. */
    UPLOAD_NULL_POINT         = -2, /* Null pointer. */
    UPLOAD_ERROR_COMMON       = -1, /* Common error. */
    UPLOAD_SUCCESS            = 0,  /* Success. */
} http2_file_upload_result_t;

Configuration options struct

typedef struct {
    uint32_t opt_bit_map;
} http2_file_upload_opt_t;

Configuration option bit definition

/* bit define of file override option */
#define UPLOAD_FILE_OPT_BIT_OVERWRITE       (0x00000001)

Return values
Value
Description
0
Success
A non-zero value
Failure

IOT_HTTP2_Disconnect

API prototype
```
int IOT_HTTP2_Disconnect(void *handle)
```
Description
This API disconnects the HTTP/2 connection. You must explicitly call this API in both the Basic Edition and Premium Edition of the SDK.
Parameters
Parameter
Data type
Direction
Description
handle
void *
Input
The connection handle.
Return values
Value
Description
0
Success
A non-zero value
Failure

Value	Description
Not NULL	Success
NULL	Failure

Value	Description
0	Success
A non-zero value	Failure

Value	Description
0	Success
A non-zero value	Failure

Value	Description
0	Success
A non-zero value	Failure