1 /**************************************************************************/ 2 /* */ 3 /* Copyright (c) Microsoft Corporation. All rights reserved. */ 4 /* */ 5 /* This software is licensed under the Microsoft Software License */ 6 /* Terms for Microsoft Azure RTOS. Full text of the license can be */ 7 /* found in the LICENSE file at https://aka.ms/AzureRTOS_EULA */ 8 /* and in the root directory of this software. */ 9 /* */ 10 /**************************************************************************/ 11 12 /**************************************************************************/ 13 /**************************************************************************/ 14 /** */ 15 /** NetX POP3 Client Component */ 16 /** */ 17 /** Post Office Protocol Version 3 (POP3) */ 18 /** */ 19 /**************************************************************************/ 20 /**************************************************************************/ 21 22 /**************************************************************************/ 23 /* */ 24 /* APPLICATION INTERFACE DEFINITION RELEASE */ 25 /* */ 26 /* nxd_pop3_client.h PORTABLE C */ 27 /* 6.1 */ 28 /* AUTHOR */ 29 /* */ 30 /* Yuxin Zhou, Microsoft Corporation */ 31 /* */ 32 /* DESCRIPTION */ 33 /* */ 34 /* This file defines the NetX Post Office Protocol Version 3 (POP3) */ 35 /* Client component, including all data types and external references. */ 36 /* It is assumed that tx_api.h, tx_port.h, nx_api.h, nx_port.h, */ 37 /* fx_api.h and fx_port.h have already been included. */ 38 /* */ 39 /* RELEASE HISTORY */ 40 /* */ 41 /* DATE NAME DESCRIPTION */ 42 /* */ 43 /* 05-19-2020 Yuxin Zhou Initial Version 6.0 */ 44 /* 09-30-2020 Yuxin Zhou Modified comment(s), */ 45 /* resulting in version 6.1 */ 46 /* */ 47 /**************************************************************************/ 48 49 #ifndef NX_POP3_CLIENT_H 50 #define NX_POP3_CLIENT_H 51 52 53 /* Determine if a C++ compiler is being used. If so, ensure that standard 54 C is used to process the API information. */ 55 56 #ifdef __cplusplus 57 58 /* Yes, C++ compiler is present. Use standard C. */ 59 extern "C" { 60 61 #endif 62 63 64 #include "nx_md5.h" 65 #include "nx_api.h" 66 67 #define NX_POP3_CLIENT_ERROR_CONSTANT 0xB0 68 69 #define NX_POP3_PARAM_ERROR (NX_POP3_CLIENT_ERROR_CONSTANT | 0x1) /* Invalid non pointer parameter passed */ 70 #define NX_POP3_INVALID_MAIL_ITEM (NX_POP3_CLIENT_ERROR_CONSTANT | 0x2) /* Client block pool not large enough to store packet payload. */ 71 #define NX_POP3_APOP_FAILED_MD5_DIGEST (NX_POP3_CLIENT_ERROR_CONSTANT | 0x3) /* Client authentication failed; MD5 digest of server ID and password failed. */ 72 #define NX_POP3_SERVER_ERROR_STATUS (NX_POP3_CLIENT_ERROR_CONSTANT | 0x4) /* Server reply appears to missing expected argument(s). */ 73 #define NX_POP3_MAIL_BUFFER_OVERFLOW (NX_POP3_CLIENT_ERROR_CONSTANT | 0x5) /* Mail data extraction has filled up mail buffer before extraction complete. */ 74 #define NX_POP3_INSUFFICIENT_PACKET_PAYLOAD (NX_POP3_CLIENT_ERROR_CONSTANT | 0x6) /* Client mail spool callback is not successful. */ 75 #define NX_POP3_CLIENT_INVALID_STATE (NX_POP3_CLIENT_ERROR_CONSTANT | 0x7)/* Client not in proper state for specific POP3 action or command. */ 76 #define NX_POP3_CLIENT_INVALID_INDEX (NX_POP3_CLIENT_ERROR_CONSTANT | 0x8) /* Client command refers to an out of bounds mail index. */ 77 78 79 80 #define NX_POP3_MAX_BINARY_MD5 16 81 #define NX_POP3_MAX_ASCII_MD5 32 82 83 #define NX_POP3_SERVER_PROCESS_ID_SIZE 75 84 85 /* POP3 Server replies */ 86 #define NX_POP3_POSITIVE_STATUS "+OK" 87 #define NX_POP3_NEGATIVE_STATUS "-ERR" 88 89 90 /* Set the maximum size for Client command and Server reply text. */ 91 92 #define NX_POP3_MAX_SERVER_REPLY 512 93 #define NX_POP3_MAX_CLIENT_COMMAND 150 94 95 /* Create symbols for common POP3 sequences. */ 96 #define NX_POP3_COMMAND_TERMINATION "\r\n" 97 #define NX_POP3_END_OF_MESSAGE_TAG ".\r\n" 98 #define NX_POP3_DOT "." 99 #define NX_POP3_END_OF_MESSAGE "\r\n.\r\n" 100 101 /* Enumerate the server POP3 replies. */ 102 #define NX_POP3_CODE_INVALID 0 103 #define NX_POP3_CODE_OK 1 104 #define NX_POP3_CODE_ERR 2 105 106 107 /* Define POP3 Client commands strings. */ 108 109 #define NX_POP3_COMMAND_GREETING "GREETING" 110 #define NX_POP3_COMMAND_USER "USER" 111 #define NX_POP3_COMMAND_APOP "APOP" 112 #define NX_POP3_COMMAND_PASS "PASS" 113 #define NX_POP3_COMMAND_STAT "STAT" 114 #define NX_POP3_COMMAND_RETR "RETR" 115 #define NX_POP3_COMMAND_DELE "DELE" 116 #define NX_POP3_COMMAND_QUIT "QUIT" 117 #define NX_POP3_COMMAND_LIST "LIST" 118 #define NX_POP3_COMMAND_RSET "RSET" 119 #define NX_POP3_COMMAND_NOOP "NOOP" 120 121 /* Determine the maximum size buffer to store messages in. This need not be 122 limited to a single packet payload of message data, since the POP3 Client 123 will receive one or more packets till it sees an end of message symbol, 124 and appends each packet message data to this buffer. */ 125 126 #ifndef NX_POP3_CLIENT_MAIL_BUFFER_SIZE 127 #define NX_POP3_CLIENT_MAIL_BUFFER_SIZE 2000 128 #endif 129 130 131 132 #ifndef NX_POP3_CLIENT_PACKET_TIMEOUT 133 #define NX_POP3_CLIENT_PACKET_TIMEOUT (1 * NX_IP_PERIODIC_RATE) 134 #endif 135 136 #ifndef NX_POP3_TCP_SOCKET_SEND_WAIT 137 #define NX_POP3_TCP_SOCKET_SEND_WAIT (10 * NX_IP_PERIODIC_RATE) 138 #endif 139 140 141 142 #ifndef NX_POP3_CLIENT_CONNECTION_TIMEOUT 143 #define NX_POP3_CLIENT_CONNECTION_TIMEOUT (30 * NX_IP_PERIODIC_RATE) 144 #endif 145 146 #ifndef NX_POP3_CLIENT_DISCONNECT_TIMEOUT 147 #define NX_POP3_CLIENT_DISCONNECT_TIMEOUT (10 * NX_IP_PERIODIC_RATE) 148 #endif 149 150 #ifndef NX_POP3_SERVER_REPLY_TIMEOUT 151 #define NX_POP3_SERVER_REPLY_TIMEOUT (10 * NX_IP_PERIODIC_RATE) 152 #endif 153 154 #ifndef NX_POP3_MAX_USERNAME 155 #define NX_POP3_MAX_USERNAME 40 156 #endif 157 158 #ifndef NX_POP3_MAX_PASSWORD 159 #define NX_POP3_MAX_PASSWORD 20 160 #endif 161 162 /* Set the size of the POP3 Client window size. This should leave room 163 for the IP and TCP headers within the IP instance MTU. */ 164 #ifndef NX_POP3_CLIENT_TCP_WINDOW_SIZE 165 #define NX_POP3_CLIENT_TCP_WINDOW_SIZE 1460 166 #endif 167 168 169 /* Define the POP3 Client structure */ 170 171 typedef struct NX_POP3_CLIENT_STRUCT 172 { 173 CHAR nx_pop3_client_name[NX_POP3_MAX_USERNAME + 1]; /* Client name (also used in authentication) */ 174 CHAR nx_pop3_client_password[NX_POP3_MAX_PASSWORD + 1]; /* Client password for authentication */ 175 NX_TCP_SOCKET nx_pop3_client_tcp_socket; /* NetX TCP client socket. */ 176 NX_PACKET_POOL *nx_pop3_client_packet_pool_ptr; /* Packet pool for allocating packets for transmitting POP3 messages */ 177 UINT nx_pop3_client_enable_APOP_authentication; /* Enable client for APOP authentication */ 178 UINT nx_pop3_client_mail_status; /* Indication if the mail item was retrieved successfully */ 179 UINT nx_pop3_client_maildrop_items; /* Number of mail messages waiting in client (user) maildrop. */ 180 UINT nx_pop3_client_maildrop_index; /* Index of current mail item. */ 181 ULONG nx_pop3_client_total_message_size; /* Size of message data in bytes sitting in client (user) maildrop. */ 182 UINT nx_pop3_client_ready_to_download; /* Indicate POP3 Client can download mail data (e.g. RETR accepted by server). */ 183 CHAR nx_pop3_server_process_id[NX_POP3_SERVER_PROCESS_ID_SIZE + 1]; 184 NX_MD5 nx_pop3_client_md5data; 185 NX_PACKET *nx_pop3_client_message_ptr; 186 } NX_POP3_CLIENT; 187 188 189 #ifndef NX_POP3_CLIENT_SOURCE_CODE 190 191 #ifdef NX_DISABLE_ERROR_CHECKING 192 193 /* Services without error checking. */ 194 195 196 #define nx_pop3_client_create _nx_pop3_client_create 197 #define nxd_pop3_client_create _nxd_pop3_client_create 198 #define nx_pop3_client_mail_items_get _nx_pop3_client_mail_items_get 199 #define nx_pop3_client_mail_item_size_get _nx_pop3_client_mail_item_size_get 200 #define nx_pop3_client_mail_item_message_get _nx_pop3_client_mail_item_message_get 201 #define nx_pop3_client_mail_item_get _nx_pop3_client_mail_item_get 202 #define nx_pop3_client_mail_item_delete _nx_pop3_client_mail_item_delete 203 #define nx_pop3_client_quit _nx_pop3_client_quit 204 #define nx_pop3_client_delete _nx_pop3_client_delete 205 206 #else 207 208 /* Services with error checking. */ 209 210 #define nx_pop3_client_create _nxe_pop3_client_create 211 #define nxd_pop3_client_create _nxde_pop3_client_create 212 #define nx_pop3_client_mail_items_get _nxe_pop3_client_mail_items_get 213 #define nx_pop3_client_mail_item_size_get _nxe_pop3_client_mail_item_size_get 214 #define nx_pop3_client_mail_item_message_get _nxe_pop3_client_mail_item_message_get 215 #define nx_pop3_client_mail_item_get _nxe_pop3_client_mail_item_get 216 #define nx_pop3_client_mail_item_delete _nxe_pop3_client_mail_item_delete 217 #define nx_pop3_client_quit _nxe_pop3_client_quit 218 #define nx_pop3_client_delete _nxe_pop3_client_delete 219 220 #endif /* if NX_DISABLE_ERROR_CHECKING */ 221 222 223 224 UINT nx_pop3_client_create(NX_POP3_CLIENT *client_ptr, UINT APOP_authentication, NX_IP *ip_ptr, NX_PACKET_POOL *packet_pool_ptr, ULONG server_ip_address, ULONG server_port, CHAR *client_name, CHAR *client_password); 225 UINT nxd_pop3_client_create(NX_POP3_CLIENT *client_ptr, UINT APOP_authentication, NX_IP *ip_ptr, NX_PACKET_POOL *packet_pool_ptr, NXD_ADDRESS *server_duo_address, ULONG server_port, CHAR *client_name, CHAR *client_password); 226 UINT nx_pop3_client_mail_items_get(NX_POP3_CLIENT *client_ptr, UINT *number_mail_items, ULONG *maildrop_total_size); 227 UINT nx_pop3_client_mail_item_size_get(NX_POP3_CLIENT *client_ptr, UINT mail_item, ULONG *size); 228 UINT nx_pop3_client_mail_item_message_get(NX_POP3_CLIENT *client_ptr, NX_PACKET **recv_packet_ptr, ULONG *bytes_retrieved, UINT *final_packet); 229 UINT nx_pop3_client_mail_item_get(NX_POP3_CLIENT *client_ptr, UINT mail_item, ULONG *item_size); 230 UINT nx_pop3_client_mail_item_delete(NX_POP3_CLIENT *client_ptr, UINT mail_index); 231 UINT nx_pop3_client_quit(NX_POP3_CLIENT *client_ptr); 232 UINT nx_pop3_client_delete(NX_POP3_CLIENT *client_ptr); 233 234 235 #else /* if NX_POP3_CLIENT_SOURCE_CODE */ 236 237 238 /* Client and session specific functions. */ 239 240 UINT _nx_pop3_client_create(NX_POP3_CLIENT *client_ptr, UINT APOP_authentication, NX_IP *ip_ptr, NX_PACKET_POOL *packet_pool_ptr, ULONG server_ip_address, ULONG server_port, CHAR *client_name, CHAR *client_password); 241 UINT _nxe_pop3_client_create(NX_POP3_CLIENT *client_ptr, UINT APOP_authentication, NX_IP *ip_ptr, NX_PACKET_POOL *packet_pool_ptr, ULONG server_ip_address, ULONG server_port, CHAR *client_name, CHAR *client_password); 242 UINT _nxd_pop3_client_create(NX_POP3_CLIENT *client_ptr, UINT APOP_authentication, NX_IP *ip_ptr, NX_PACKET_POOL *packet_pool_ptr, NXD_ADDRESS *server_duo_address, ULONG server_port, CHAR *client_name, CHAR *client_password); 243 UINT _nxde_pop3_client_create(NX_POP3_CLIENT *client_ptr, UINT APOP_authentication, NX_IP *ip_ptr, NX_PACKET_POOL *packet_pool_ptr, NXD_ADDRESS *server_duo_address, ULONG server_port, CHAR *client_name, CHAR *client_password); 244 UINT _nx_pop3_client_mail_items_get(NX_POP3_CLIENT *client_ptr, UINT *number_mail_items, ULONG *maildrop_total_size); 245 UINT _nxe_pop3_client_mail_items_get(NX_POP3_CLIENT *client_ptr, UINT *number_mail_items, ULONG *maildrop_total_size); 246 UINT _nx_pop3_client_mail_item_size_get(NX_POP3_CLIENT *client_ptr, UINT mail_item, ULONG *size); 247 UINT _nxe_pop3_client_mail_item_size_get(NX_POP3_CLIENT *client_ptr, UINT mail_item, ULONG *size); 248 UINT _nx_pop3_client_mail_item_message_get(NX_POP3_CLIENT *client_ptr, NX_PACKET **recv_packet_ptr, ULONG *bytes_retrieved, UINT *final_packet); 249 UINT _nxe_pop3_client_mail_item_message_get(NX_POP3_CLIENT *client_ptr, NX_PACKET **recv_packet_ptr, ULONG *bytes_retrieved, UINT *final_packet); 250 UINT _nx_pop3_client_mail_item_get(NX_POP3_CLIENT *client_ptr, UINT mail_item, ULONG *item_size); 251 UINT _nxe_pop3_client_mail_item_get(NX_POP3_CLIENT *client_ptr, UINT mail_item, ULONG *item_size); 252 UINT _nx_pop3_client_mail_item_delete(NX_POP3_CLIENT *client_ptr, UINT mail_index); 253 UINT _nxe_pop3_client_mail_item_delete(NX_POP3_CLIENT *client_ptr, UINT mail_index); 254 UINT _nx_pop3_client_delete(NX_POP3_CLIENT *client_ptr); 255 UINT _nxe_pop3_client_delete(NX_POP3_CLIENT *client_ptr); 256 UINT _nx_pop3_client_quit(NX_POP3_CLIENT *client_ptr); 257 UINT _nxe_pop3_client_quit(NX_POP3_CLIENT *client_ptr); 258 259 #endif 260 261 /* NetX POP3 Client internal functions */ 262 263 UINT _nx_pop3_digest_authenticate(NX_POP3_CLIENT *client_ptr, CHAR *process_ID_ptr, UINT process_ID_length, CHAR *result); 264 VOID _nx_pop3_parse_process_id(NX_POP3_CLIENT *client_ptr, CHAR *buffer, UINT buffer_length); 265 VOID _nx_pop3_hex_ascii_convert(CHAR *source, UINT source_length, CHAR *destination); 266 UINT _nxd_pop3_client_connect(NX_POP3_CLIENT *client_ptr, NXD_ADDRESS *server_ip_address, ULONG server_port); 267 UINT _nx_pop3_server_number_convert(UINT number, CHAR *string_to_convert); 268 VOID _nx_pop3_parse_response(CHAR *buffer, UINT argument_index, UINT buffer_length, CHAR *argument, UINT argument_length, UINT convert_to_uppercase, UINT include_crlf); 269 UINT _nx_pop3_client_user_pass(NX_POP3_CLIENT *client_ptr); 270 UINT _nx_pop3_client_apop(NX_POP3_CLIENT *client_ptr); 271 272 273 /* If a C++ compiler is being used....*/ 274 #ifdef __cplusplus 275 } 276 #endif 277 278 279 #endif /* NX_POP3_CLIENT_H */ 280
