1 /*************************************************************************** 2 * Copyright (c) 2024 Microsoft Corporation 3 * 4 * This program and the accompanying materials are made available under the 5 * terms of the MIT License which is available at 6 * https://opensource.org/licenses/MIT. 7 * 8 * SPDX-License-Identifier: MIT 9 **************************************************************************/ 10 11 12 /**************************************************************************/ 13 /**************************************************************************/ 14 /** */ 15 /** NetX Duo Component */ 16 /** */ 17 /** Hypertext Transfer Protocol (HTTP) */ 18 /** */ 19 /**************************************************************************/ 20 /**************************************************************************/ 21 22 23 /**************************************************************************/ 24 /* */ 25 /* APPLICATION INTERFACE DEFINITION RELEASE */ 26 /* */ 27 /* nxd_http_client.h PORTABLE C */ 28 /* 6.1.6 */ 29 /* AUTHOR */ 30 /* */ 31 /* Yuxin Zhou, Microsoft Corporation */ 32 /* */ 33 /* DESCRIPTION */ 34 /* */ 35 /* This file defines the NetX Hypertext Transfer Protocol (HTTP) */ 36 /* component, including all data types and external references. */ 37 /* It is assumed that nx_api.h and nx_port.h have already been */ 38 /* included, along with fx_api.h and fx_port.h. */ 39 /* */ 40 /* RELEASE HISTORY */ 41 /* */ 42 /* DATE NAME DESCRIPTION */ 43 /* */ 44 /* 05-19-2020 Yuxin Zhou Initial Version 6.0 */ 45 /* 09-30-2020 Yuxin Zhou Modified comment(s), */ 46 /* resulting in version 6.1 */ 47 /* 04-02-2021 Yuxin Zhou Modified comment(s), and */ 48 /* improved the logic of */ 49 /* parsing base64, */ 50 /* resulting in version 6.1.6 */ 51 /* */ 52 /**************************************************************************/ 53 54 #ifndef NXD_HTTP_CLIENT_H 55 #define NXD_HTTP_CLIENT_H 56 57 /* Determine if a C++ compiler is being used. If so, ensure that standard 58 C is used to process the API information. */ 59 60 61 #ifdef __cplusplus 62 63 /* Yes, C++ compiler is present. Use standard C. */ 64 extern "C" { 65 66 #endif 67 68 #include "nx_api.h" 69 70 /* Define the HTTP ID. */ 71 72 #define NXD_HTTP_CLIENT_ID 0x48545450UL 73 74 75 /* Define HTTP TCP socket create options. */ 76 77 #ifndef NX_HTTP_TYPE_OF_SERVICE 78 #define NX_HTTP_TYPE_OF_SERVICE NX_IP_NORMAL 79 #endif 80 81 #ifndef NX_HTTP_FRAGMENT_OPTION 82 #define NX_HTTP_FRAGMENT_OPTION NX_DONT_FRAGMENT 83 #endif 84 85 #ifndef NX_HTTP_TIME_TO_LIVE 86 #define NX_HTTP_TIME_TO_LIVE 0x80 87 #endif 88 89 #ifndef NX_HTTP_MAX_RESOURCE 90 #define NX_HTTP_MAX_RESOURCE 40 91 #endif 92 93 #ifndef NX_HTTP_MAX_NAME 94 #define NX_HTTP_MAX_NAME 20 95 #endif 96 97 #ifndef NX_HTTP_MAX_PASSWORD 98 #define NX_HTTP_MAX_PASSWORD 20 99 #endif 100 101 #ifndef NX_HTTP_CLIENT_TIMEOUT 102 #define NX_HTTP_CLIENT_TIMEOUT (10 * NX_IP_PERIODIC_RATE) 103 #endif 104 105 #ifndef NX_PHYSICAL_TRAILER 106 #define NX_PHYSICAL_TRAILER 4 107 #endif 108 109 #ifndef NX_HTTP_CLIENT_MIN_PACKET_SIZE 110 #define NX_HTTP_CLIENT_MIN_PACKET_SIZE 600 111 #endif 112 113 /* NX_HTTP_MAX_STRING is base64 of "name:password" and plus 1 if an extra conversion is needed and plus 2 pad if needed. */ 114 #define NX_HTTP_MAX_STRING ((NX_HTTP_MAX_NAME + NX_HTTP_MAX_PASSWORD + 1) * 4 / 3 + 1 + 2) 115 #define NX_HTTP_MAX_BINARY_MD5 16 116 #define NX_HTTP_MAX_ASCII_MD5 32 117 118 119 /* Define HTTP Client states. */ 120 121 #define NX_HTTP_CLIENT_STATE_READY 1 122 #define NX_HTTP_CLIENT_STATE_GET 2 123 #define NX_HTTP_CLIENT_STATE_PUT 3 124 125 126 /* Define return code constants. */ 127 128 #define NX_HTTP_ERROR 0xE0 /* HTTP internal error */ 129 #define NX_HTTP_TIMEOUT 0xE1 /* HTTP timeout occurred */ 130 #define NX_HTTP_FAILED 0xE2 /* HTTP error */ 131 #define NX_HTTP_DONT_AUTHENTICATE 0xE3 /* HTTP authentication not needed */ 132 #define NX_HTTP_BASIC_AUTHENTICATE 0xE4 /* HTTP basic authentication requested */ 133 #define NX_HTTP_DIGEST_AUTHENTICATE 0xE5 /* HTTP digest authentication requested */ 134 #define NX_HTTP_NOT_FOUND 0xE6 /* HTTP request not found */ 135 #define NX_HTTP_DATA_END 0xE7 /* HTTP end of content area */ 136 #define NX_HTTP_CALLBACK_COMPLETED 0xE8 /* HTTP user callback completed the processing */ 137 #define NX_HTTP_POOL_ERROR 0xE9 /* HTTP supplied pool payload is too small */ 138 #define NX_HTTP_NOT_READY 0xEA /* HTTP client not ready for operation */ 139 #define NX_HTTP_AUTHENTICATION_ERROR 0xEB /* HTTP client authentication failed */ 140 #define NX_HTTP_GET_DONE 0xEC /* HTTP client get is complete */ 141 #define NX_HTTP_BAD_PACKET_LENGTH 0xED /* Invalid packet received - length incorrect */ 142 #define NX_HTTP_REQUEST_UNSUCCESSFUL_CODE 0xEE /* Received an error code instead of 2xx from server */ 143 #define NX_HTTP_INCOMPLETE_PUT_ERROR 0xEF /* Server responds before PUT is complete */ 144 #define NX_HTTP_PASSWORD_TOO_LONG 0xF0 /* Password exceeded expected length */ 145 #define NX_HTTP_USERNAME_TOO_LONG 0xF1 /* Username exceeded expected length */ 146 #define NX_HTTP_NO_QUERY_PARSED 0xF2 /* Server unable to find query in client request */ 147 148 /* Define the default HTTP Server TCP port number. To change this at runtime 149 see nx_http_client_set_connect_port(). */ 150 151 #define NX_HTTP_SERVER_PORT 80 152 153 154 #ifdef NX_HTTP_DIGEST_ENABLE 155 156 /* Include the MD5 digest header file. */ 157 158 #include "nx_md5.h" 159 160 #endif 161 162 163 /* Define the HTTP Client data structure. */ 164 165 typedef struct NX_HTTP_CLIENT_STRUCT 166 { 167 ULONG nx_http_client_id; /* HTTP Server ID */ 168 CHAR *nx_http_client_name; /* Name of this HTTP Client */ 169 UINT nx_http_client_state; /* Current state of HTTP Client */ 170 UINT nx_http_client_connect_port; /* Client port to connect to the server */ 171 NX_IP *nx_http_client_ip_ptr; /* Pointer to associated IP structure */ 172 NX_PACKET_POOL *nx_http_client_packet_pool_ptr; /* Pointer to HTTP Client packet pool */ 173 ULONG nx_http_client_total_transfer_bytes; /* Total number of bytes to transfer */ 174 ULONG nx_http_client_actual_bytes_transferred; /* Number of bytes actually transferred */ 175 NX_PACKET *nx_http_client_first_packet; /* Pointer to first packet with data */ 176 NX_TCP_SOCKET nx_http_client_socket; /* HTTP Client TCP socket */ 177 #ifdef NX_HTTP_DIGEST_ENABLE 178 NX_MD5 nx_http_client_md5data; /* HTTP Client MD5 work area */ 179 #endif 180 } NX_HTTP_CLIENT; 181 182 183 184 #ifndef NX_HTTP_SOURCE_CODE 185 186 /* Application caller is present, perform API mapping. */ 187 188 /* Determine if error checking is desired. If so, map API functions 189 to the appropriate error checking front-ends. Otherwise, map API 190 functions to the core functions that actually perform the work. 191 Note: error checking is enabled by default. */ 192 193 #ifdef NX_DISABLE_ERROR_CHECKING 194 195 /* Services without error checking. */ 196 197 #define nx_http_client_create _nx_http_client_create 198 #define nx_http_client_delete _nx_http_client_delete 199 #define nx_http_client_get_start _nx_http_client_get_start 200 #define nx_http_client_get_start_extended _nx_http_client_get_start_extended 201 #define nx_http_client_get_packet _nx_http_client_get_packet 202 #define nx_http_client_put_start _nx_http_client_put_start 203 #define nx_http_client_put_start_extended _nx_http_client_put_start_extended 204 #define nx_http_client_put_packet _nx_http_client_put_packet 205 #define nx_http_client_set_connect_port _nx_http_client_set_connect_port 206 #define nxd_http_client_get_start _nxd_http_client_get_start 207 #define nxd_http_client_get_start_extended _nxd_http_client_get_start_extended 208 #define nxd_http_client_put_start _nxd_http_client_put_start 209 #define nxd_http_client_put_start_extended _nxd_http_client_put_start_extended 210 211 #else 212 213 /* Services with error checking. */ 214 215 #define nx_http_client_create(p,n,i,pp,w) _nxe_http_client_create(p,n,i,pp,w, sizeof(NX_HTTP_CLIENT)) 216 #define nx_http_client_delete _nxe_http_client_delete 217 #define nx_http_client_get_start _nxe_http_client_get_start 218 #define nx_http_client_get_start_extended _nxe_http_client_get_start_extended 219 #define nx_http_client_get_packet _nxe_http_client_get_packet 220 #define nx_http_client_put_start _nxe_http_client_put_start 221 #define nx_http_client_put_start_extended _nxe_http_client_put_start_extended 222 #define nx_http_client_put_packet _nxe_http_client_put_packet 223 #define nx_http_client_set_connect_port _nxe_http_client_set_connect_port 224 #define nxd_http_client_put_start _nxde_http_client_put_start 225 #define nxd_http_client_put_start_extended _nxde_http_client_put_start_extended 226 #define nxd_http_client_get_start _nxde_http_client_get_start 227 #define nxd_http_client_get_start_extended _nxde_http_client_get_start_extended 228 229 #endif /* NX_DISABLE_ERROR_CHECKING */ 230 231 /* Define the prototypes accessible to the application software. */ 232 233 #ifdef NX_DISABLE_ERROR_CHECKING 234 UINT _nx_http_client_create(NX_HTTP_CLIENT *client_ptr, CHAR *client_name, NX_IP *ip_ptr, NX_PACKET_POOL *pool_ptr, ULONG window_size); 235 #else 236 UINT _nxe_http_client_create(NX_HTTP_CLIENT *client_ptr, CHAR *client_name, NX_IP *ip_ptr, NX_PACKET_POOL *pool_ptr, ULONG window_size, UINT http_client_size); 237 #endif /* NX_DISABLE_ERROR_CHECKING */ 238 UINT nx_http_client_delete(NX_HTTP_CLIENT *client_ptr); 239 UINT nx_http_client_get_start(NX_HTTP_CLIENT *client_ptr, ULONG ip_address, CHAR *resource, CHAR *input_ptr, UINT input_size, CHAR *username, CHAR *password, ULONG wait_option); 240 UINT nx_http_client_get_start_extended(NX_HTTP_CLIENT *client_ptr, ULONG ip_address, CHAR *resource, UINT resource_length, CHAR *input_ptr, UINT input_size, CHAR *username, UINT username_length, CHAR *password, UINT password_length, ULONG wait_option); 241 UINT nx_http_client_get_packet(NX_HTTP_CLIENT *client_ptr, NX_PACKET **packet_ptr, ULONG wait_option); 242 UINT nx_http_client_put_start(NX_HTTP_CLIENT *client_ptr, ULONG ip_address, CHAR *resource, CHAR *username, CHAR *password, ULONG total_bytes, ULONG wait_option); 243 UINT nx_http_client_put_start_extended(NX_HTTP_CLIENT *client_ptr, ULONG ip_address, CHAR *resource, UINT resource_length, CHAR *username, UINT username_length, CHAR *password, UINT password_length, ULONG total_bytes, ULONG wait_option); 244 UINT nx_http_client_put_packet(NX_HTTP_CLIENT *client_ptr, NX_PACKET *packet_ptr, ULONG wait_option); 245 UINT nx_http_client_set_connect_port(NX_HTTP_CLIENT *client_ptr, UINT port); 246 UINT nxd_http_client_get_start(NX_HTTP_CLIENT *client_ptr, NXD_ADDRESS *ip_address, CHAR *resource, CHAR *input_ptr, UINT input_size, CHAR *username, CHAR *password, ULONG wait_option); 247 UINT nxd_http_client_get_start_extended(NX_HTTP_CLIENT *client_ptr, NXD_ADDRESS *ip_address, CHAR *resource, UINT resource_length, CHAR *input_ptr, UINT input_size, CHAR *username, UINT username_length, CHAR *password, UINT password_length, ULONG wait_option); 248 UINT nxd_http_client_put_start(NX_HTTP_CLIENT *client_ptr, NXD_ADDRESS *ip_address, CHAR *resource, CHAR *username, CHAR *password, ULONG total_bytes, ULONG wait_option); 249 UINT nxd_http_client_put_start_extended(NX_HTTP_CLIENT *client_ptr, NXD_ADDRESS *ip_address, CHAR *resource, UINT resource_length, CHAR *username, UINT username_length, CHAR *password, UINT password_length, ULONG total_bytes, ULONG wait_option); 250 251 #else 252 253 /* HTTP source code is being compiled, do not perform any API mapping. */ 254 255 UINT _nxe_http_client_create(NX_HTTP_CLIENT *client_ptr, CHAR *client_name, NX_IP *ip_ptr, NX_PACKET_POOL *pool_ptr, ULONG window_size, UINT http_client_size); 256 UINT _nx_http_client_create(NX_HTTP_CLIENT *client_ptr, CHAR *client_name, NX_IP *ip_ptr, NX_PACKET_POOL *pool_ptr, ULONG window_size); 257 UINT _nxe_http_client_delete(NX_HTTP_CLIENT *client_ptr); 258 UINT _nx_http_client_delete(NX_HTTP_CLIENT *client_ptr); 259 UINT _nxe_http_client_get_start(NX_HTTP_CLIENT *client_ptr, ULONG ip_address, CHAR *resource, CHAR *input_ptr, UINT input_size, CHAR *username, CHAR *password, ULONG wait_option); 260 UINT _nx_http_client_get_start(NX_HTTP_CLIENT *client_ptr, ULONG ip_address, CHAR *resource, CHAR *input_ptr, UINT input_size, CHAR *username, CHAR *password, ULONG wait_option); 261 UINT _nxe_http_client_get_start_extended(NX_HTTP_CLIENT *client_ptr, ULONG ip_address, CHAR *resource, UINT resource_length, CHAR *input_ptr, UINT input_size, CHAR *username, UINT username_length, CHAR *password, UINT password_length, ULONG wait_option); 262 UINT _nx_http_client_get_start_extended(NX_HTTP_CLIENT *client_ptr, ULONG ip_address, CHAR *resource, UINT resource_length, CHAR *input_ptr, UINT input_size, CHAR *username, UINT username_length, CHAR *password, UINT password_length, ULONG wait_option); 263 UINT _nxe_http_client_get_packet(NX_HTTP_CLIENT *client_ptr, NX_PACKET **packet_ptr, ULONG wait_option); 264 UINT _nx_http_client_get_packet(NX_HTTP_CLIENT *client_ptr, NX_PACKET **packet_ptr, ULONG wait_option); 265 UINT _nxe_http_client_put_start(NX_HTTP_CLIENT *client_ptr, ULONG ip_address, CHAR *resource, CHAR *username, CHAR *password, ULONG total_bytes, ULONG wait_option); 266 UINT _nx_http_client_put_start(NX_HTTP_CLIENT *client_ptr, ULONG ip_address, CHAR *resource, CHAR *username, CHAR *password, ULONG total_bytes, ULONG wait_option); 267 UINT _nxe_http_client_put_start_extended(NX_HTTP_CLIENT *client_ptr, ULONG ip_address, CHAR *resource, UINT resource_length, CHAR *username, UINT username_length, CHAR *password, UINT password_length, ULONG total_bytes, ULONG wait_option); 268 UINT _nx_http_client_put_start_extended(NX_HTTP_CLIENT *client_ptr, ULONG ip_address, CHAR *resource, UINT resource_length, CHAR *username, UINT username_length, CHAR *password, UINT password_length, ULONG total_bytes, ULONG wait_option); 269 UINT _nxe_http_client_put_packet(NX_HTTP_CLIENT *client_ptr, NX_PACKET *packet_ptr, ULONG wait_option); 270 UINT _nx_http_client_put_packet(NX_HTTP_CLIENT *client_ptr, NX_PACKET *packet_ptr, ULONG wait_option); 271 UINT _nxe_http_client_set_connect_port(NX_HTTP_CLIENT *client_ptr, UINT port); 272 UINT _nx_http_client_set_connect_port(NX_HTTP_CLIENT *client_ptr, UINT port); 273 UINT _nxde_http_client_get_start(NX_HTTP_CLIENT *client_ptr, NXD_ADDRESS *ip_address, CHAR *resource, CHAR *input_ptr, UINT input_size, CHAR *username, CHAR *password, ULONG wait_option); 274 UINT _nxd_http_client_get_start(NX_HTTP_CLIENT *client_ptr, NXD_ADDRESS *ip_address, CHAR *resource, CHAR *input_ptr, UINT input_size, CHAR *username, CHAR *password, ULONG wait_option); 275 UINT _nxde_http_client_get_start_extended(NX_HTTP_CLIENT *client_ptr, NXD_ADDRESS *ip_address, CHAR *resource, UINT resource_length, CHAR *input_ptr, UINT input_size, CHAR *username, UINT username_length, CHAR *password, UINT password_length, ULONG wait_option); 276 UINT _nxd_http_client_get_start_extended(NX_HTTP_CLIENT *client_ptr, NXD_ADDRESS *ip_address, CHAR *resource, UINT resource_length, CHAR *input_ptr, UINT input_size, CHAR *username, UINT username_length, CHAR *password, UINT password_length, ULONG wait_option); 277 UINT _nxde_http_client_put_start(NX_HTTP_CLIENT *client_ptr, NXD_ADDRESS *ip_address, CHAR *resource, CHAR *username, CHAR *password, ULONG total_bytes, ULONG wait_option); 278 UINT _nxd_http_client_put_start(NX_HTTP_CLIENT *client_ptr, NXD_ADDRESS *ip_address, CHAR *resource, CHAR *username, CHAR *password, ULONG total_bytes, ULONG wait_option); 279 UINT _nxde_http_client_put_start_extended(NX_HTTP_CLIENT *client_ptr, NXD_ADDRESS *ip_address, CHAR *resource, UINT resource_length, CHAR *username, UINT username_length, CHAR *password, UINT password_length, ULONG total_bytes, ULONG wait_option); 280 UINT _nxd_http_client_put_start_extended(NX_HTTP_CLIENT *client_ptr, NXD_ADDRESS *ip_address, CHAR *resource, UINT resource_length, CHAR *username, UINT username_length, CHAR *password, UINT password_length, ULONG total_bytes, ULONG wait_option); 281 282 /* Define internal HTTP functions. */ 283 284 UINT _nx_http_client_type_get(CHAR *name, CHAR *http_type_string); 285 UINT _nx_http_client_content_length_get(NX_PACKET *packet_ptr); 286 UINT _nx_http_client_calculate_content_offset(NX_PACKET *packet_ptr); 287 UINT _nx_http_client_number_convert(UINT number, CHAR *string); 288 289 290 #endif /* NX_HTTP_SOURCE_CODE */ 291 292 /* Determine if a C++ compiler is being used. If so, complete the standard 293 C conditional started above. */ 294 #ifdef __cplusplus 295 } 296 #endif 297 298 #endif /* NXD_HTTP_CLIENT_H */ 299
