Beruflich Dokumente
Kultur Dokumente
RT-IP
C
H A P T E R
Rev. 12/01/1998
1
RT-IP/POP3
SMTP
SMTP/POP3
RT-IP
RT-IP/POP3
SMTP
SMTP/POP3
RT-IP
RTIP SMTP/POP3
CHAPTER TWO CONFIGURING SMTP AND POP3
C
H A P T E R
RT-IP/POP3
SMTP
SMTP/POP3
Configuring SMTP and POP The following defines are set by the makefile: INCLUDE_RTFS INCLUDE_DOS_FS
RT-IP
- Specifies that the file system to use to access web pages on disk should be RTFS. - Specifies that the file system to use to access web pages on disk should be DOS.
The following defines for SMTP and POP are in xnconf.h CFG_MAIL_TIMEOUT CFG_MAX_FROM_LEN - Timeout in seconds when waiting for a response from server. - The maximum length of from field in MIME header.
CFG_MAX_SUBJECT_LEN - The maximum length of subject field in MIME header. Configuring SMTP: The following defines for SMTP are in xnconf.h CFG_SMTP_MAX_RCPTS CFG_SMTP_BUF_SIZE - The maximum # of recipients for a message. - The size of the buffer for server response. Configuring POP: The following defines for POP are in xnconf.h CFG_POP_BUF_SIZE - The size of the buffer for server response.
CFG_POP_MAX_BOUNDARY - The maximum boundary length saved; used to determine end of message when reading a multi-part mime message.
RT-IP/POP3
SMTP
SMTP/POP3
RT-IP
C
H A P T E R
RT-IP/POP3
SMTP
10
SMTP/POP3
SMTP: Simple Mail Transfer Protocol Introduction:
RT-IP
The purpose of SMTP is to allow an SMTP client to send an email message to an SMTP server. The client connects to TCP port 25, the SMTP port, and sends a greeting of the form HELO domain, where domain is the domain name of the client. The server response consists of a result code followed by any optional text and ending with a <CRLF> pair. The client then uses the MAIL FROM: command to specify the author of the message, and the RCPT TO: command to specify the recipients. Note that if the message has multiple recipients, this command may be used more than once for a single message. The client then sends the DATA command, which informs the server that what follows is the mail message. The client then sends the message, terminated by <CRLF>.<CRLF>. The QUIT command is used to close the connection. A typical SMTP client-server interaction is as follows: S: < waits for connection on TCP port 25 > ... C: < connects to TCP port 25 > S: < sends optional greeting > C: HELO linux.etcbin.com S: 250 OK C: MAIL FROM: john@etcbin.com S: 250 OK C: RCPT TO: moe@etcbin.com S: 250 OK C: RCPT TO: larry@etcbin.com S: 250 OK C: DATA S: 354 send mail data, end with . C: < sends the email message with appropriate termination sequence > S: 250 OK C: QUIT S: 221 OK closing connection. In general, result codes that begin with 2 or 3 are positive, while those that begin with 4 or 5 indicate an error.
Introduction:
11
RT-IP/POP3
SMTP
12
SMTP/POP3
RT-IP
RTIP SMTP/POP3
CHAPTER FOUR SMTP API
C
H A P T E R
13
RT-IP/POP3
SMTP
14
SMTP/POP3
Function: xn_smtp() - send mail message through SMTP Summary: #include smtp.h int xn_smtp(info) PSMTP_INFO info Description:
RT-IP
This function sends an email message using the SMTP protocol. The string char *from will appear in the From: section of the message. Recipients are not listed by default. To include a list of recipients at the beginning of a message, simply prepend this list onto the body of the message. The format of the parameter is: /* receipient of mail message */ struct rcpt { char name[80]; }; /* parameter to xn_smtp */ typedef struct _smtp_info { byte smtp_server_ip[IP_ALEN]; char reverse_path[200]; char from[CFG_MAX_FROM_LEN]; char subject[CFG_MAX_SUBJECT_LEN]; struct rcpt rcpts[CFG_SMTP_MAX_RCPTS]; PFCHAR PFCHAR int PFCHAR PFCHAR body; body_file; num_rcpts; attach attach_file;
/* IP address of SMTP server */ /* domain name of sender */ /* email address of author */ /* subject of message */ /* list of recipients */ /* body of message */ /* (set to 0 if body not in a buffer) */ /* filename for body of message */ /* (set to 0 if body not in a file) */ /* # of recipients */ /* attachment buffer */ /* (set to 0 if no buffer attachment) */ /* filename of attachment */ /* (set to 0 if no attachment) */
xn_smtp
15
RT-IP/POP3
PFCHAR attach_type
SMTP
/* attachment type (text/plain */ /* application octet-stream, etc.) */ /* Note: any type other than text/plain will be */ /* base64 encoded. */
} smtp_info; typedef struct _smtp_info KS_FAR *PSMTP_INFO; Returns: 0 on success, -1 upon failure. If an error occurred, call xn_getlasterror and xn_geterror_string to return the error value. Appendix B of the RTIP Reference Manual further describes each error. Possible values for this function are: ESMTPSERVDOWN ESMTPBADRESP Example: See Appendix A - The SMTP Server is not responding - The SMTP Server returned error
16
SMTP/POP3
RT-IP
RTIP SMTP/POP3
CHAPTER FIVE POP INTRODUCTION
C
H A P T E R
17
RT-IP/POP3
SMTP
18
SMTP/POP3
POP3 Introduction
RT-IP
The purpose of POP is to allow a client to retrieve email messages from a server. The POP client establishes a TCP connection to port 110, the POP port, and the POP server sends back a greeting. The POP Client then sends login information, using the USER and PASS commands. The POP server responds starting with +OK if the login was valid and -ERR if the login was invalid. The POP Client may then send the STAT command, in response to which the POP server will send a reply of the form +OK n m, where n is the number of messages and m is the size of the mail file. The POP Client may then send the LIST command, which lists the size of each mail message individually. Commands of the form RETR n and DELE n may be used to retrieve and delete messages, respectively, where n is the number of the message. A typical dialogue between POP client and server is as follows: S: <wait for connection on TCP port 110 > ... C: < open connection > S: +OK POP3 Server ready . . . C: USER johndoe S: +OK User name ok, enter password: C: PASS redclover S: +OK Password accepted. C: STAT S: +OK 5 1142 C: LIST S: +OK Mail listing follows: S: 1 212 S: 2 315 S: 3 100 S: 4 405 S: 5 110 S: . C: RETR 1 S: +OK 212 octets S: <POP server sends entire message> C: DELE 1 S: +OK deleting message 1. C: QUIT S: +OK bye The POP Client uses the QUIT command to terminate the session. Another important command available to the POP Client is of the form TOP n, where n is a message number. The server will send back the header from message n.
Introduction
19
RT-IP/POP3
SMTP
20
SMTP/POP3
RT-IP
RTIP SMTP/POP3
CHAPTER SIX POP3 API
C
H A P T E R
Chapter 6 Table of Contents xn_pop_checkmail ..................................... 23 xn_pop_client ............................................ 24 xn_pop_DELE ........................................... 25 xn_pop_mailinfo ....................................... 26 xn_pop_mailsize ........................................ 27 xn_pop_QUIT ........................................... 28 xn_pop_RETR_done ................................. 29 xn_pop_RETR_next .................................. 30
21
RT-IP/POP3
SMTP
22
SMTP/POP3
Function: xn_pop_checkmail() - returns mailbox info Summary: #include pop.h int xn_pop_checkmail(context, info) PPOP_CONTEXT context PPOP_INFO info Description: client context structure in which to put mail info
RT-IP
Once you are connected to a POP server (i.e. once xn_pop_client has been called) you may call xn_pop_checkmail to obtain the number of messages in the mailbox and the size of the mail file. The function xn_pop_checkmail fills in the fields in an instance of pop_info, which is declared as follows: struct pop_info { int num_messages; long mail_size; }; typedef struct _pop_info KS_FAR *PPOP_INFO; The number of the messages will be put into num_messages, and the total size of the mail file will be put into mail_size. Returns: Returns 0 upon success, otherwise -1. If an error occurred, call xn_getlasterror and xn_geterror_string to return the error value. Appendix B of the RTIP Reference Manual further describes each error. Possible values for this function are: ESRVDOWN ESRVBADRESP Example: See Appendix A
xn_pop_checkmail
23
RT-IP/POP3
Function: xn_pop_client() - connects to POP server and checks mail Summary: #include pop.h int xn_pop_client(context, pop_server_ip, username, pass) PPOP_CONTEXT context PFBYTE pop_server_ip PFCHAR username PFCHAR pass Description: client context servers IP address username to log in to POP server password to log in to POP server
SMTP
This function connects to a POP server and to the server. The function xn_pop_QUIT needs to be called to close the connection after all the information needed (i.e. all calls to xn_pop_RETR_next, xn_pop_checkmail, etc.) have been made. Returns: Returns 0 upon success, otherwise -1. If an error occurred, call xn_getlasterror and xn_geterror_string to return the error value. Appendix B of the RTIP Reference Manual further describes each error. Possible values for this function are: ESRVDOWN ESRVBADRESP Example: See Appendix A - Server not responding - Server sent invalid response or error.
xn_pop_client
24
SMTP/POP3
Function: xn_pop_DELE() - deletes a mail message Summary: #include pop.h int xn_pop_DELE(context, num); ppop_context context int num Description: client context index of message to delete
RT-IP
This routine deletes a mail message from the POP server. Each message on the server is identified with an index. The message whose index is num will be deleted from the server. Returns: Returns 0 upon success, otherwise -1. If an error occurred, call xn_getlasterror and xn_geterror_string to return the error value. Appendix B of the RTIP Reference Manual further describes each error. Possible values for this function are: ESRVDOWN ESRVBADRESP Example: See Appendix A - Server not responding - Server sent invalid response or error.
xn_pop_DELE
25
RT-IP/POP3
Function: xn_pop_mailinfo() Summary: #include pop.h int xn_pop_mailinfo(context, info, msg_num) PPOP_CONTEXT context PPOP_MSG_INFO info int msg_num Description: client context structure in which to put mail info message number - returns mailbox info
SMTP
Once you are connected to a POP server (i.e. once xn_pop_client has been called) you may call xn_pop_mailinfo to obtain the other information about a mail message, i.e. this function fills in the fields in an instance of struct pop_msg_info. For each message, the senders address and the subject will be written to the parameter info. The structure pop_msg_info is declared as follows: struct pop_msg_info { char from[100]; char subject[100]; }; The sender address and subject into from and subject, respectively. Returns: Returns 0 upon success, otherwise -1. If an error occurred, call xn_getlasterror and xn_geterror_string to return the error value. Appendix B of the RTIP Reference Manual further describes each error. Possible values for this function are: ESRVDOWN ESRVBADRESP Example: See Appendix A Server not responding - Server sent invalid response or error.
xn_pop_mailinfo
26
SMTP/POP3
Function: xn_pop_mailsize() - returns mailbox info Summary: #include pop.h int xn_pop_mailsize(context, mail_sizes, first_msg, len) PPOP_CONTEXT context PFLONG mail_sizes int first_msg int num_msgs Description: client context array to be filled in with mail sizes first mail message to get mail sizes for size of mail_sizes
RT-IP
Once you are connected to a POP server (i.e. once xn_pop_client has been called) you may call xn_pop_mailsize to obtain the sizes of the mail messages. The sizes of messages first_msg through (num_msgs-first_msg) are obtained. The sizes obtained are written to the array mail_sizes. For each message, the message size will be put at the index (message number - first_msg), i.e. the size of mail message first_msg is written at offset 0, the size of the first_msg+1 is written at offset 1, etc. Any unsued entries in mail_sizes are set to -1. Returns: Returns 0 upon success, otherwise -1. If an error occurred, call xn_getlasterror and xn_geterror_string to return the error value. Appendix B of the RTIP Reference Manual further describes each error. Possible values for this function are: ESRVDOWN ESRVBADRESP Example: See Appendix A - Server not responding - Server sent invalid response or error.
xn_pop_mailsize
27
RT-IP/POP3
Function: xn_pop_QUIT() - logs out of POP server and closes connection Summary: int xn_pop_QUIT(context) PPOP_CONTEXT context Description: - client context
SMTP
This routine logs out of the POP server that was connected to via xn_pop_client and closes the connection. This routine should be called at the end of any POP client application. Returns: Returns 0 upon success, otherwise -1. If an error occurred, call xn_getlasterror and xn_geterror_string to return the error value. Appendix B of the RTIP Reference Manual further describes each error. Possible values for this function are: ESRVDOWN Example: See Appendix A - Server not responding
xn_pop_QUIT
28
SMTP/POP3
Function: xn_pop_RETR_done() - cleans up after calls to xn_pop_RETR_next Summary: #include pop.h int xn_pop_RETR_done(context) PPOP_CONTEXT context - client context Description:
RT-IP
This routine should be called after all calls to xn_pop_RETR_next to retrieve a mail message have been done. It reads any residue data from the socket and sets the context to the proper state for reading another mail message. Returns: Returns 0 upon success, otherwise -1. If an error occurred, call xn_getlasterror and xn_geterror_string to return the error value. Appendix B of the RTIP Reference Manual further describes each error. Possible values for this function are: ESRVDOWN Example: See Appendix A Server not responding
xn_pop_RETR_done
29
RT-IP/POP3
Function: xn_pop_RETR_next() - retrieves next part of message from POP server Summary: #include pop.h int xn_pop_RETR_next(context, num, parse_info) PPOP_CONTEXT context int num PMIME_PARSE_INFO parse_info Description: client context number of mail message to retrieve results are written to this structure
SMTP
This function retrieves the next field of a mail message where the possible fields are a MAIL header field, a MIME header field, as much data of MAIL or ATTACHMENT message as can fit in context->pop_buffer (or up to a \r\n). The results of the field read are put in parse_info, i.e. the type of field read is put in parse_info->mime_type and a pointer to the body of the field is written to parse_info->mime_field_ptr. The length of the body of the field is written to parse_info->mime_field_len. NOTE: the same context structure must be passed between calls to this function NOTE: calling this routine overwrites data in context->pop_buffer (i.e parse_info>mime_field_ptr is set to the start of the body in context->pop_buffer), therefore, any data in the buffer from the previous call must be processed before calling this routine. The format of parse_info structure is: typedef struct _mime_parse_info { int mime_type; /* mime type - see below*/ PFCHAR mime_field_ptr; /* pointer to body of mime field*/ int mime_field_len; /* length of body of the mime field*/ } mime_parse_info; typedef struct _mime_parse_info KS_FAR *PMIME_PARSE_INFO; The support mime types include: MIME_RETURN_PATH MIME_RECEIVED MIME_DATE MIME_FROM MIME_MESSAGE_ID MIME_SUBJECT
xn_pop_RETR_next
30
SMTP/POP3
MIME_VERSION MIME_CONTENT_TYPE MIME_STATUS MIME_CONTENT_ENCODE MIME_CONTENT_DISP MAIL ATTACH Returns:
RT-IP
Returns 0 upon success, otherwise -1. If an error occurred, call xn_getlasterror and xn_geterror_string to return the error value. Appendix B of the RTIP Reference Manual further describes each error. Possible values for this function are: ESRVDOWN ESRVBADRESP - Server not responding - Server sent invalid response or error.
31
RT-IP/POP3
SMTP
32
SMTP/POP3
RT-IP
A
P P E N D I X
APPENDIX A EXAMPLES
Chapter 1 Table of Contents SMTP examples ......................................... 35 POP3 example ........................................... 38 POP3 example ........................................... 40 POP3 example ........................................... 41
33
RT-IP/POP3
SMTP
34
SMTP/POP3
/* ************************************************************* /* SMTP EXAMPLE /* /* Description: /* This examples demonstrate sending mail messages. /* /* NOTE: there is an interactive example in smtpcli.c in the apps directory /* /* /* This example demonstrates the following: /* - Calling xn_smtp to send a mail message /* /* #define SMTP_BUF_SIZE 2000 struct _smtp_info KS_FAR smtp_param; char KS_FAR body_buffer[SMTP_BUF_SIZE]; char KS_FAR body_file[80]; char KS_FAR attach_file[80]; /* send a mail message to 1 receipients from a buffer without an attachment */ void smtp_send_mail(void) { /* initialize parameter to xn_smtp */ smtp_param.attach_file = (PFCHAR)0; smtp_param.body_file = (PFCHAR)0; smtp_param.body = body_buffer; tc_strcpy(smtp_param.reverse_path, joe@etcbin.com); /* set up to send the mail message to paul */ smtp_param.num_rcpts = 1; tc_strcpy(smtp_param.rcpts[0].name, paul@etcbin.com); /* set up the subject field */ tc_strcpy(smtp_param.subject, test); /* set up the message */ tc_strcpy(smtp_param.body, this is a test message); /* send the message */ if (xn_smtp(&smtp_param) < 0) { printf(Call to xn_smtp failed); } }
RT-IP
*/ */ */ */ */ */ */ */ */ */ */ */ */
SMTP EXAMPLE
35
RT-IP/POP3
/* send a mail message to 1 receipients from a file without an attachment */ void smtp_send_mail(void) { /* initialize parameter to xn_smtp */ smtp_param.attach_file = (PFCHAR)0; smtp_param.body_file = body_file; smtp_param.body = (PFCHAR)0; tc_strcpy(smtp_param.reverse_path, joe@etcbin.com); /* set up to send the mail message to paul and mary */ smtp_param.num_rcpts = 1; tc_strcpy(smtp_param.rcpts[1].name, mary@etcbin.com); /* set up the subject field */ tc_strcpy(smtp_param.subject, test); /* set up the message */ tc_strcpy(smtp_param.body_file, mail1.txt); /* send the message */ if (xn_smtp(&smtp_param) < 0) { printf(Call to xn_smtp failed); } }
SMTP
/* send a mail message to 2 receipients from a buffer with one attachment */ void smtp_send_mail(void) { /* initialize parameter to xn_smtp */ smtp_param.attach_file = attach_file; smtp_param.body_file = (PFCHAR)0; smtp_param.body = body_buffer; smtp_param.body[0] = \0; tc_strcpy(smtp_param.reverse_path, joe@etcbin.com); /* set up to send the mail message to paul and mary */ smtp_param.num_rcpts = 2; tc_strcpy(smtp_param.rcpts[0].name, paul@etcbin.com); tc_strcpy(smtp_param.rcpts[1].name, mary@etcbin.com); /* set up the subject field */ tc_strcpy(smtp_param.subject, test); /* set up the message */
36
SMTP/POP3
tc_strcpy(smtp_param.body, this is a test message); /* set up to send an attachment (attachments are always files) */ tc_strcpy(smtp_param.attach_file, attach1.txt); /* send the message */ if (xn_smtp(&smtp_param) < 0) { printf(Call to xn_smtp failed); } }
RT-IP
37
RT-IP/POP3
/* ************************************************************* /* POP3 EXAMPLE /* /* Description: /* This examples demonstrate displaying available mail messages. /* /* This example demonstrates the following: /* - Calling xn_pop_client to connect to server /* - Calling xn_pop_checkmail to get the number of mail messages /* - Calling xn_pop_mailsize to get the sizes of all all mail messages /* - Calling xn_pop_mailinfo to get information on each mail message /* - Calling xn_pop_quit to terminate the connection /* /* /* /* Parameters: /* pop_srv_ip_addr - POP servers IP address /* username - username for use in logging on to pop server /* password - password for use in logging on to pop server /*
SMTP
*/ */ */ */ */ */ */ */ */ */ */ */ */ */ */ */ */ */ */
#define NUM_MAIL_MSGS 10 struct _pop_msg_size mail sizes[MAIL_BUF_SIZE]; void pop_display_mail(PFBYTE pop_srv_ip_addr, PFCHAR username, PFCHAR password) { struct _pop_context context; struct _pop_msg_info msg; PPOP_MSG_SIZE mail_sizes; int mail_num; int first_msg; int n; int msg_left; int max_msgs; /* connect to the POP3 Server */ if (xn_pop_client((PPOP_CONTEXT)&context, pop_srv_ip_addr, username, password) == -1) { printf(xn_pop_client failed.), return(-1); } /* get number of messages available */ if (xn_pop_checkmail(context, info) < 0) { printf(xn_pop_checkmail failed), return; }
38
POP3 EXAMPLE
SMTP/POP3
printf(You have %d messages\n, info->num_messages); if (info->num_messages == 0) return; max_msgs = MAX_MAIL_MSGS; if (info -> num_messages < MAX_MAIL_MSGS) max_msg = info -> num_messages; msg_left = info -> num_messages; while (msg_left > 0) { if (max_msg > msg_left) max_msg = msg_left; /* get mail sizes for current set of mail messages */ if (xn_pop_mailsize(context, mail_sizes, first_msg, max_msg)) { printf(xn_pop_mailsize failed); return; }
RT-IP
printf(# size sender subject); for (n = 0; n < max_msg; n++) { mail_num = mail_sizes[n].num; if (xn_pop_mailinfo(context, (PPOP_MSG_INFO)&msg, mail_num)) { printf(xn_pop_mailinfo failed-msg num, offset = %d %d\n, mail_num, n); continue; } /* print the results */ printf(%5d%7d%s%s\n, mail_num, mail_sizes[n].size, msg.from, msg.subject); } msg_left -= max_msg; first_msg += max_msg; } if (xn_pop_QUIT((PPOP_CONTEXT)&context) == -1) { printf(xn_pop_QUIT failed.); return; } }
39
RT-IP/POP3
/* /* /* /* /* /* /* /* /* /* /* /* /* /* /* /* /* /* /* /* /* /* /* ************************************************************* POP3 EXAMPLE Description: This examples demonstrate retrieving a mail message. NOTE: there is an interactive example in popcli.c in the apps directory This example demonstrates the following: - Calling xn_pop_client to connect to server - Calling xn_pop_RETR_next to retrieve field of mail message - Calling xn_pop_RETR_done to finish the retrieve - Calling xn_pop_quit to terminate the connection
SMTP
*/ */ */ */ */ */ */ */ */ */ */ */ */ */ */ */ */
POP servers IP address message number to retrieve username for use in logging on to pop server password for use in logging on to pop server
void pop_display_mail(PFBYTE pop_srv_ip_addr, int msg_num, PFCHAR username, PFCHAR password) { struct _pop_context context; mime_parse_info parse_info; if (xn_pop_client((PPOP_CONTEXT)&context, pop_srv_ip_addr, username, password) == -1) { printf(xn_pop_client failed.); return; } while ( (xn_pop_RETR_next((PPOP_CONTEXT)&context, msg_num, (PMIME_PARSE_INFO)&parse_info) != -1)) { printf(%s: %s, mime_headers[mime_type].mime_header, parse_info.mime_field_ptr); } xn_pop_RETR_done((PPOP_CONTEXT)&context); if (xn_pop_QUIT((PPOP_CONTEXT)&context) == -1) { printf(xn_pop_QUIT failed.); return; } }
40
POP3 EXAMPLE
SMTP/POP3
/* ************************************************************* /* POP3 EXAMPLE /* /* Description: /* This examples demonstrate deleting a mail message. /* /* NOTE: there is an interactive example in popcli.c in the apps directory /* /* /* This example demonstrates the following: /* - Calling xn_pop_client to connect to server /* - Calling xn_pop_DELE_next to delete a mail message /* - Calling xn_pop_quit to terminate the connection /* /* /* /* Parameters: /* pop_srv_ip_addr - POP servers IP address /* msg_num - message number to retrieve /* username - username for use in logging on to pop server /* password - password for use in logging on to pop server /* void pop_display_mail(PFBYTE pop_srv_ip_addr, int msg_num, PFCHAR username, PFCHAR password) { struct _pop_context context;
RT-IP
*/ */ */ */ */ */ */ */ */ */ */ */ */ */ */ */ */ */ */ */ */ */
if (xn_pop_client((PPOP_CONTEXT)&context, pop_srv_ip_addr, username, password) == -1) { printf(xn_pop_client failed.); return; } if (xn_pop_DELE(PPOP_CONTEXT)&context,msg_num)<0) { printf(delete of mail message %%d failed,msg_num); } if (xn_pop_QUIT((PPOP_CONTEXT)&context) == -1) { printf(xn_pop_QUIT failed.); return; } }
POP3 EXAMPLE
41
RT-IP/POP3
SMTP
42