SMTP Email Engine Library for C/C++ (SEE4C) REFERENCE MANUAL Version 1.0 June 1, 1998 This software is provided as-is. There are no warranties, expressed or implied. Copyright (C) 1998 All rights reserved MarshallSoft Computing, Inc. Post Office Box 4543 Huntsville AL 35815 Voice : 256-881-4630 FAX : 256-880-0925 email : info@marshallsoft.com web : www.marshallsoft.com _______ ____|__ | (R) --+ | +------------------- | ____|__ | Association of | | |_| Shareware |__| o | Professionals --+--+ | +--------------------- |___|___| MEMBER SEE4C Reference Manual Page 1 C O N T E N T S Chapter Page Table of Contents.............................2 General Remarks...............................3 SEE Functions.................................3 seeClose...................................3 seeConnectTo...............................4 seeDriver..................................5 seeErrorText...............................6 seeIntegerParam............................7 seeSendEmail...............................8 seeStatistics..............................9 seeStringParam............................10 seeVerifyFormat...........................11 SEE Error Codes..............................12 SEE4C Reference Manual Page 2 General Remarks All functions return an integer code. Negative values are always errors. See section "SEE Error Codes". Non-negative return codes are never errors. Allocate all buffers passed to SEE statically, rather than dynamically on the stack. You can always force any variable declaration to be staticslly allocated by use of the "static" keyword, for example: static char Buffer[64]; SEE Functions +----------+--------------------------------------------------------+ | seeClose | Closes SMTP Email Engine. | +----------+--------------------------------------------------------+ SYNTAX int seeClose(void) REMARKS The seeClose function closes the connection created by calling seeConnectTo. seeConnectTo can be called again to open a connection to another SMTP server if desired. Normally, there is only one seeConnectTo and one seeClose in your program. RETURNS < 0 : An error has occured. See the error list. EXAMPLE // call after sending all email. seeClose(); ALSO SEE seeConnectTo. SEE4C Reference Manual Page 3 +--------------+----------------------------------------------------+ | seeConnectTo | Connects to SMTP server. | +--------------+----------------------------------------------------+ SYNTAX int seeConnectTo( LPSTR Server, // SMTP server. LPSTR From, // Your email address in brackets. LPSTR ReplyTo) // Email address to reply to. REMARKS The seeConnectTo function establishes a connection with the SMTP server as specified by the Server argument. Your SMTP server name will typically be named "mail.XXX.com" where XXX is your email address, such as name@XXX.com. Your SMTP server name can also be found in the setup information for your normal email client, such as Eudora or Microsoft Outlook. The SMTP server name can also be specified in dotted decimal notation if wanted. For example "10.23.231.1". The From string is required and must be enclosed in "<>" brackets, such as . The ReplyTo string is optional and is used for the "Reply-To:" header line. If used, the email address must be enclosed in "<>" brackets. RETURNS < 0 : An error has occured. See the error list. EXAMPLE seeConnect("mail.myisp.com", // my SMTP server "", // my email address NULL); // no Reply-To seeConnect("mail.myisp.com", // my SMTP server "", // my email address "; // Reply-To address ALSO SEE seeClose. SEE4C Reference Manual Page 4 +-----------+-------------------------------------------------------+ | seeDriver | Executes next SEE state. | +-----------+-------------------------------------------------------+ SYNTAX int seeDriver(void) REMARKS The seeDriver function executes the next state in SEE16.DLL or SEE32.DLL after calling seeConnectTo, seeSendEmail, or seeClose provided that the AUTO_DRIVER_CALL flag is disabled. The purpose of this function is to allow the programmer to get control after the driver executes each state. RETURNS = 0 : The driver is done. < 0 : An error has occured. See the error list. > 0 : The returned value is the state just executed. EXAMPLE int Code; . . . [call seeConnectTo] . . . // disable automatic calling of seeDriver(). seeIntegerParam(AUTO_DRIVER_CALL, 0); Code = seeSendEmail(...); if(Code<0) {printf("Error %d\n", Code); exit(1); } while(1) {Code = seeDriver(); if(Code<0) {printf("Error %d\n", Code); exit(1); } /* display all but "wait" state */ if(Code!=9999) printf("%d ",Code); if(Code==0) return 0; } } ALSO SEE seeIntegerParam SEE4C Reference Manual Page 5 +--------------+----------------------------------------------------+ | seeErrorText | Get text associated with error code. | +--------------+----------------------------------------------------+ SYNTAX int seeErrorText( int Code, // Error code returned by SEE function. LPSTR Buffer, // Buffer to place error text into. int BufLen) // Length of above Buffer. REMARKS The seeErrorText function is used to get the error text associated with an an error code as returned by selConnectTo, seeSendEmail, seeClose, or seeDriver. When an error occurs, seeErrorText can be used to get the error text so that it can be displayed for the user. EXAMPLE static char Buffer[80]; . . . Code = seeConnectTo("mail.myserver.com", "", NULL); if(Code<0) {seeErrorText(Code,Buffer,80); printf("ERROR %d: %s\n", Code, Buffer); exit(1); } ALSO SEE SEE4C Reference Manual Page 6 +-----------------+-------------------------------------------------+ | seeIntegerParam | Sets SEE integer parameter. | +-----------------+-------------------------------------------------+ SYNTAX int seeIntegerParam( int ParmIndex, // Parameter index (see below). ULONG ParmValue) // Value of parameter to set. REMARKS The seeIntegerParam is used to set an integer parameter as defined in SEE.H. For more information, refer to the Users Manual. All times are in milliseconds. Parameter Name Default SEE_MIN_RESPONSE_WAIT : 500 SEE_MAX_RESPONSE_WAIT : 10000 SEE_MIN_LINE_WAIT : 5 SEE_MAX_LINE_WAIT : 10000 SEE_CONNECT_WAIT : 60000 SEE_QUOTED_PRINTABLE : 0 SEE_AUTO_CALL_DRIVER : 1 SEE_MIN_RESPONSE_WAIT is the delay before looking for the server's response. SEE_MAX_RESPONSE_WAIT is the time after which a "time-out" error ocurrs if the server has not responded. SEE_MIN_LINE_WAIT is the delay before checking if the server is ready to accept the next line of input. SEE_MAX_LINE_WAIT is the time after which a "time-out" error is declared if the server has not responded. SEE_CONNECT_WAIT is the maximum time allowed to complete a connection to the SMTP server. SEE_QUOTED_PRINTABLE controls the whether messages are (1) or are not (0) encoded as quoted-printable. SEE_AUTO_CALL_DRIVER controls whether ssDriver is called automatically (to completion) after seeConnectTo, seeSendEmail, or seeClose is called. EXAMPLE /* disable auto call feature */ seeIntegerParam(SEE_AUTO_CALL_DRIVER, 0); ALSO SEE seeStringParam. SEE4C Reference Manual Page 7 +--------------+----------------------------------------------------+ | seeSendEmail | Sends email and attachments. | +--------------+----------------------------------------------------+ SYNTAX int seeSendEmail( LPSTR To, // Receipient, separated by commas. LPSTR CC, // CC list, separated by commas. LPSTR BCC, // BCC list, separated by commas. LPSTR Subj, // Subject text. LPSTR Msg, // Message or message filename. LPSTR Attach) // File attachment. REMARKS The seeSendEmail function is used to send email once a conection has been made to your SMTP server after calling seeConnectTo. Note that all email addresses (in To, CC, and BCC strings) must be bracketed. For example: The CC and BCC strings may contain multiple email addresses, separted by commas. For example: "Billy Bob,Buster" If the first character of the message (fifth argument) is a '@', then it is considered as the filename which contains the message to send. RETURNS < 0 : An error has occured. See the error list. EXAMPLE seeSendEmail("", /* receipient */ NULL, /* CC list */ NULL, /* BCC list */ "Hello", /* subject */ "Call me ASAP!", /* message */ NULL); /* attachment */ ALSO SEE seeConnectTo SEE4C Reference Manual Page 8 +---------------+---------------------------------------------------+ | seeStatistics | Returns runtime statistics. | +---------------+---------------------------------------------------+ SYNTAX ULONG seeStatistics( int Index) // Specifies which statistic. REMARKS The seeStatistics function is used to return runtime statistics in the SEE DLL. The values of Index are defined in SEE.H as follows: SEE_GET_SOCK_ERROR : Gets last socket error. SEE_GET_COUNTER : Gets # times driver called. SEE_GET_RESPONSE : Gets last SMTP response code. SEE_GET_MESSAGE_BYTES_READ : Gets # message bytes read. SEE_GET_ATTACH_BYTES_READ : Gets # attachment bytes read. SEE_GET_TOTAL_BYTES_READ : Gets total of above two. SEE_GET_MESSAGE_BYTES_SENT : Gets # message bytes sent. SEE_GET_ATTACH_BYTES_SENT : Gets # attachment bytes sent. SEE_GET_TOTAL_BYTES_SENT : Gets total of above two. The number of message bytes sent will usually be larger than your message size because of SMTP protocol overhead. The number of attachment bytes sent will be at least one-third larger than the actual attachment since every 3 bytes are encoded as 4 7-bit ASCII bytes before being transmitted. The purpose of "...BYTES_READ" and "...BYTES_SENT" is to provide the ability to track the tranmission progress of large messages and attachments. See the DRIVER example program. EXAMPLE // get total message & attachment bytes transmitted. Code = seeStatistics(SEE_GET_TOTAL_BYTES_SENT); ALSE SEE seeDriver, seeIntegerParam and seeStringParam. SEE4C Reference Manual Page 9 +----------------+--------------------------------------------------+ | seeStringParam | Sets SEE string parameter. | +----------------+--------------------------------------------------+ SYNTAX int seeStringParam( int ParamName, // Index of parameter. LPSTR ParamString) // Parameter string. REMARKS The seeStringParam function is used to set a string parameter as defined in SEE.H. For more information, refer to the Users Manual. SEE_LOG_FILE : Specifies the log filename. The log file is used to debug a SMTP session. Be advised that log files can be quite large. Don't use them unless neccessary. EXAMPLE seeStringParam(SEE_LOG_FILE, "mytest.log"); ALSO SEE seeIntegerParam SEE4C Reference Manual Page 10 +-----------------+-------------------------------------------------+ | seeVerifyFormat | Check email address format. | +-----------------+-------------------------------------------------+ SYNTAX int seeVerifyFormat( LPSTR String) // Email address to check. REMARKS The seeVerifyFormat function is use to test an individual email address for proper formatting. If this function returns 0 or above, then the email address is properly formatted. But, if this function returns a negative value, the email address is either badly formatted, or it uses characters (such as '%') that are not normally used as part of an email address. Note that left and right brackets ('<' and '>') must surround the email address. EXAMPLE static char Buffer[80]; . . . Code = seeVerifyFormat("Billy E. Bob"); if(Code<0) {seeErrorText(Code,Buffer,80); printf("Email address error : %s\n", Buffer); exit(1); } ALSO SEE seeErrorText SEE4C Reference Manual Page 11 SEE Error Codes +-----------------------+-----------------------------------------+ | SEE_NO_ERROR | No error. | | SEE_CANNOT_COMPLY | Cannot comply. Not always an error. | +-----------------------+-----------------------------------------+ | SEE_EOF | End of file (socket has been closed). | | SEE_IS_BLOCKING | Socket is currently blocking. | | SEE_BAD_DOTTED | Bad dotted address. | | SEE_TIMED_OUT | Socket timed out awaiting data. | | SEE_ABORTED | The DLL has been corrupted. | | SEE_ALREADY_CONNECTED | Already connected to server. | | SEE_BACK_OVERFLOW | Response buffer has overflowed. | | SEE_BAD_ADDRESS_CHAR | Bad character in email address. | | SEE_CANNOT_ATTACH | Cannot access WINSOCK | | SEE_CANNOT_OPEN | Cannot open file. | | SEE_CONNECT_ERROR | Error attempting to connect. | | SEE_EMPTY_ADDRESS | EMPTY email address. | | SEE_FROM_NULL_ARG | FromPtr is NULL. | | SEE_MISSING_AT_CHAR | Missing '@' character in email address. | | SEE_MISSING_FROM | Missing FROM email address. | | SEE_MISSING_LEFT | Missing '<' delimiter in email address. | | SEE_MISSING_RIGHT | Missing '>' terminating email address. | | SEE_NOT_CONNECTED | Not connected to server | | SEE_NO_RECEIPIENTS | Must have at least one receipient. | | SEE_NO_SERVER | Cannot find Smtp server. | | SEE_NULL_POINTER | Unexpected NULL pointer. | | SEE_RCPT_NULL_ARG | ToPtr is NULL. | | SEE_SMTP_ERROR | SMTP returned error. | | SEE_SMTP_NULL_ARG | SMTP Server not specified. | | SEE_SOCK_READ_ERROR | Socket read error. | | SEE_SOCK_WRITE_ERROR | Socket write error. | | SEE_TOO_MANY_AT_CHARS | Too many '@' symbols in email address. | +-----------------------+-----------------------------------------+ NOTES: (1) All error codes are negative. (2) Numerical error codes are defined in DEFINES.H. (3) SEE_ABORTED will be returned if the DLL has been modified. You should never get this message! SEE4C Reference Manual Page 12