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