source: azure_iot_hub/trunk/azure_iohub/c-utility/inc/azure_c_shared_utility/httpapi.h@ 388

Last change on this file since 388 was 388, checked in by coas-nagasima, 5 years ago

Azure IoT Hub Device C SDK を使ったサンプルの追加
  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
  • Property svn:mime-type set to text/x-chdr
File size: 8.9 KB
Line 
1// Copyright (c) Microsoft. All rights reserved.
2// Licensed under the MIT license. See LICENSE file in the project root for full license information.
3
4/** @file httpapi.h
5 * @brief This module implements the standard HTTP API used by the C IoT client
6 * library.
7 *
8 * @details For example, on the Windows platform the HTTP API code uses
9 * WinHTTP and for Linux it uses curl and so forth. HTTPAPI must support
10 * HTTPs (HTTP+SSL).
11 */
12
13#ifndef HTTPAPI_H
14#define HTTPAPI_H
15
16#include "azure_c_shared_utility/httpheaders.h"
17#include "azure_c_shared_utility/macro_utils.h"
18#include "azure_c_shared_utility/buffer_.h"
19#include "azure_c_shared_utility/umock_c_prod.h"
20
21#ifdef __cplusplus
22#include <cstddef>
23extern "C" {
24#else
25#include <stddef.h>
26#endif
27
28typedef struct HTTP_HANDLE_DATA_TAG* HTTP_HANDLE;
29
30#define AMBIGUOUS_STATUS_CODE (300)
31
32#define HTTPAPI_RESULT_VALUES \
33HTTPAPI_OK, \
34HTTPAPI_INVALID_ARG, \
35HTTPAPI_ERROR, \
36HTTPAPI_OPEN_REQUEST_FAILED, \
37HTTPAPI_SET_OPTION_FAILED, \
38HTTPAPI_SEND_REQUEST_FAILED, \
39HTTPAPI_RECEIVE_RESPONSE_FAILED, \
40HTTPAPI_QUERY_HEADERS_FAILED, \
41HTTPAPI_QUERY_DATA_AVAILABLE_FAILED, \
42HTTPAPI_READ_DATA_FAILED, \
43HTTPAPI_ALREADY_INIT, \
44HTTPAPI_NOT_INIT, \
45HTTPAPI_HTTP_HEADERS_FAILED, \
46HTTPAPI_STRING_PROCESSING_ERROR, \
47HTTPAPI_ALLOC_FAILED, \
48HTTPAPI_INIT_FAILED, \
49HTTPAPI_INSUFFICIENT_RESPONSE_BUFFER, \
50HTTPAPI_SET_X509_FAILURE, \
51HTTPAPI_SET_TIMEOUTS_FAILED \
52
53/** @brief Enumeration specifying the possible return values for the APIs in
54 * this module.
55 */
56MU_DEFINE_ENUM(HTTPAPI_RESULT, HTTPAPI_RESULT_VALUES);
57
58#define HTTPAPI_REQUEST_TYPE_VALUES\
59 HTTPAPI_REQUEST_GET, \
60 HTTPAPI_REQUEST_POST, \
61 HTTPAPI_REQUEST_PUT, \
62 HTTPAPI_REQUEST_DELETE, \
63 HTTPAPI_REQUEST_PATCH, \
64 HTTPAPI_REQUEST_HEAD \
65
66
67/** @brief Enumeration specifying the HTTP request verbs accepted by
68 * the HTTPAPI module.
69 */
70MU_DEFINE_ENUM(HTTPAPI_REQUEST_TYPE, HTTPAPI_REQUEST_TYPE_VALUES);
71
72#define MAX_HOSTNAME_LEN 65
73#define MAX_USERNAME_LEN 65
74#define MAX_PASSWORD_LEN 65
75
76/**
77 * @brief Global initialization for the HTTP API component.
78 *
79 * Platform specific implementations are expected to initialize
80 * the underlying HTTP API stacks.
81 *
82 * @return @c HTTPAPI_OK if initialization is successful or an error
83 * code in case it fails.
84 */
85MOCKABLE_FUNCTION(, HTTPAPI_RESULT, HTTPAPI_Init);
86
87/** @brief Free resources allocated in ::HTTPAPI_Init. */
88MOCKABLE_FUNCTION(, void, HTTPAPI_Deinit);
89
90/**
91 * @brief Creates an HTTPS connection to the host specified by the @p
92 * hostName parameter.
93 *
94 * @param hostName Name of the host.
95 *
96 * This function returns a handle to the newly created connection.
97 * You can use the handle in subsequent calls to execute specific
98 * HTTP calls using ::HTTPAPI_ExecuteRequest.
99 *
100 * @return A @c HTTP_HANDLE to the newly created connection or @c NULL in
101 * case an error occurs.
102 */
103MOCKABLE_FUNCTION(, HTTP_HANDLE, HTTPAPI_CreateConnection, const char*, hostName);
104
105/**
106 * @brief Closes a connection created with ::HTTPAPI_CreateConnection.
107 *
108 * @param handle The handle to the HTTP connection created via ::HTTPAPI_CreateConnection.
109 *
110 * All resources allocated by ::HTTPAPI_CreateConnection should be
111 * freed in ::HTTPAPI_CloseConnection.
112 */
113MOCKABLE_FUNCTION(, void, HTTPAPI_CloseConnection, HTTP_HANDLE, handle);
114
115/**
116 * @brief Sends the HTTP request to the host and handles the response for
117 * the HTTP call.
118 *
119 * @param handle The handle to the HTTP connection created
120 * via ::HTTPAPI_CreateConnection.
121 * @param requestType Specifies which HTTP method is used (GET,
122 * POST, DELETE, PUT, PATCH).
123 * @param relativePath Specifies the relative path of the URL
124 * excluding the host name.
125 * @param httpHeadersHandle Specifies a set of HTTP headers (name-value
126 * pairs) to be added to the
127 * HTTP request. The @p httpHeadersHandle
128 * handle can be created and setup with
129 * the proper name-value pairs by using the
130 * HTTPHeaders APIs available in @c
131 * HTTPHeaders.h.
132 * @param content Specifies a pointer to the request body.
133 * This value is optional and can be @c NULL.
134 * @param contentLength Specifies the request body size (this is
135 * typically added into the HTTP headers as
136 * the Content-Length header). This value is
137 * optional and can be 0.
138 * @param statusCode This is an out parameter, where
139 * ::HTTPAPI_ExecuteRequest returns the status
140 * code from the HTTP response (200, 201, 400,
141 * 401, etc.)
142 * @param responseHeadersHandle This is an HTTP headers handle to which
143 * ::HTTPAPI_ExecuteRequest must add all the
144 * HTTP response headers so that the caller of
145 * ::HTTPAPI_ExecuteRequest can inspect them.
146 * You can manipulate @p responseHeadersHandle
147 * by using the HTTPHeaders APIs available in
148 * @c HTTPHeaders.h
149 * @param responseContent This is a buffer that must be filled by
150 * ::HTTPAPI_ExecuteRequest with the contents
151 * of the HTTP response body. The buffer size
152 * must be increased by the
153 * ::HTTPAPI_ExecuteRequest implementation in
154 * order to fit the response body.
155 * ::HTTPAPI_ExecuteRequest must also handle
156 * chunked transfer encoding for HTTP responses.
157 * To manipulate the @p responseContent buffer,
158 * use the APIs available in @c Strings.h.
159 *
160 * @return @c HTTPAPI_OK if the API call is successful or an error
161 * code in case it fails.
162 */
163MOCKABLE_FUNCTION(, HTTPAPI_RESULT, HTTPAPI_ExecuteRequest, HTTP_HANDLE, handle, HTTPAPI_REQUEST_TYPE, requestType, const char*, relativePath,
164 HTTP_HEADERS_HANDLE, httpHeadersHandle, const unsigned char*, content,
165 size_t, contentLength, unsigned int*, statusCode,
166 HTTP_HEADERS_HANDLE, responseHeadersHandle, BUFFER_HANDLE, responseContent);
167
168/**
169 * @brief Sets the option named @p optionName bearing the value
170 * @p value for the HTTP_HANDLE @p handle.
171 *
172 * @param handle The handle to the HTTP connection created via
173 * ::HTTPAPI_CreateConnection.
174 * @param optionName A @c NULL terminated string representing the name
175 * of the option.
176 * @param value A pointer to the value for the option.
177 *
178 * @return @c HTTPAPI_OK if initialization is successful or an error
179 * code in case it fails.
180 */
181MOCKABLE_FUNCTION(, HTTPAPI_RESULT, HTTPAPI_SetOption, HTTP_HANDLE, handle, const char*, optionName, const void*, value);
182
183/**
184 * @brief Clones the option named @p optionName bearing the value @p value
185 * into the pointer @p savedValue.
186 *
187 * @param optionName A @c NULL terminated string representing the name of
188 * the option
189 * @param value A pointer to the value of the option.
190 * @param savedValue This pointer receives the copy of the value of the
191 * option. The copy needs to be free-able.
192 *
193 * @return @c HTTPAPI_OK if initialization is successful or an error
194 * code in case it fails.
195 */
196MOCKABLE_FUNCTION(, HTTPAPI_RESULT, HTTPAPI_CloneOption, const char*, optionName, const void*, value, const void**, savedValue);
197
198#ifdef __cplusplus
199}
200#endif
201
202#endif /* HTTPAPI_H */
Note: See TracBrowser for help on using the repository browser.