SMTP C API Reference
Table of Contents | Previous
| Next
| Index
Messaging Access SDK Guide
Part 2. Messaging Access SDK C Reference
This chapter describes the functions and structures of the C language API for the SMTP (Simple Mail Transfer Protocol) protocol of the Messaging Access SDK.
You'll find links to each function and structure in this introduction. Each reference entry gives the name of the function or structure, its header file, its syntax, and its parameters.
All C interface definitions are found in the smtp.h file.
[Top]
This table lists SMTP functions alphabetically by name, with descriptions. Click the function name to get information about it.
[Top] [SMTP Functions] [SMTP Functions by Task]
Sends binary data chunks to the server.
#include <smtp.h>
int smtp_bdat( smtpClient_t * in_pSMTP,
const char * in_data,
unsigned int length,
boolean in_fLast);
The function has the following parameters:
This function sends data in binary chunks of the size you determine. Call smtp_bdat multiple times until the boolean value in the in_fLast parameter is set to true.
If you use the smtp_send or smtp_sendStream function, send data with smtp_data and not with smtp_bdat. For more information, see Sending the Message.
This function sends the DATA SMTP protocol command.
NOTE:
bdat is not supported by Messaging Server 4.0. Use smtp_data instead. §
This function is mapped to one or more callbacks in the smtpSink_t.bdat, smtpSink_t.error, smtp_data,
smtp_sendStream, smtp_send,
[Top] [SMTP Functions] [SMTP Functions by Task]
Connects to the server using the specified port.
#include <smtp.h>
int smtp_connect( smtpClient_t * in_pSMTP,
const char * in_server,
unsigned short in_port );
The function has the following parameters:
For more information, see Connecting to a Server.
This function is mapped to one or more callbacks in the smtpSink_t.connect, smtpSink_t.error,
smtp_quit, smtp_ehlo
[Top] [SMTP Functions] [SMTP Functions by Task]
Prepares to send data to the server.
#include <smtp.h>
int smtp_data(smtpClient_t * in_pSMTP);
The function has the following parameters:
This function sends data in conjunction with smtp_send or smtp_sendstream. Call smtp_data, then call one of these functions. You must always use smtp_data and not smtp_bdat with either of these functions. This function sends the DATA SMTP protocol command. For more information, see Sending the Message.
This function is mapped to one or more callbacks in the smtpSink_t.data, smtpSink_t.error, smtp_bdat,
smtp_send, smtp_sendStream
[Top] [SMTP Functions] [SMTP Functions by Task]
Closes the socket connection with the server.
#include <smtp.h>
int smtp_disconnect( smtpClient_t * in_pSMTP );
The function has the following parameters:
This function closes the socket connection. It could be used to implement a Cancel button.
NOTE:
Do not call the SMTP_processResponses function after this function.
Operations for which you do not call processResponses: disconnecting, the
set functions, initializing and freeing the client and sink. §
smtp_connect, smtp_ehlo
[Top] [SMTP Functions] [SMTP Functions by Task]
Starts the SMTP session
#include <smtp.h>
int smtp_ehlo( smtpClient_t * in_pSMTP,
const char * in_domain );
The function has the following parameters:
This function returns a multiline message listing the SMTP extensions, such as pipelining or DSN, that are supported by the server. This is similar to the functionality of the IMAP4 capability command. This function sends the EHLO SMTP protocol command. For more information, see Determining ESMTP Support.
This function is mapped to one or more callbacks in the smtpSink_t.ehlo, smtpSink_t.error,
smtpSink_t.ehloComplete, smtp_connect,
imap4_capability
[Top] [SMTP Functions] [SMTP Functions by Task]
Expands the specified mailing list.
#include <smtp.h>
int smtp_expand(smtpClient_t * in_pSMTP,
const char * in_mailingList);
The function has the following parameters:
This function gets the email addresses of the users on the mailing list. It sends the smtpSink_t.expand, smtpSink_t.expandComplete,
smtpSink_t.error
[Top] [SMTP Functions] [SMTP Functions by Task]
Frees the SMTPClient_t structure.
#include <smtp.h>
void smtp_free( smtpClient_t ** in_ppSMTP );
The function has the following parameters:
This function frees the SMTPClient_t structure. When the function returns, the client structure is set to null. The user must free any pointers to opaque data.
smtp_initialize, smtpSink_free
[Top] [SMTP Functions] [SMTP Functions by Task]
Gets IO models.
#include <smtp.h>
int smtp_get_option( smtpClient_t * in_pSMTP,
int in_option,
void * in_pOptionData );
The function has the following parameters:
This Do not call processResponses after this function.
smtp_set_option
[Top] [SMTP Functions] [SMTP Functions by Task]
Asks the server for help on a specified topic.
#include <smtp.h>
int smtp_help( smtpClient_t * in_pSMTP,
const char * in_helpTopic);
The function has the following parameters:
This function asks the server for help on a specified topic. It sends the HELP SMTP protocol command.
This function is mapped to one or more callbacks in the smtpSink_t.help, smtpSink_t.helpComplete, smtpSink_t.error
[Top] [SMTP Functions] [SMTP Functions by Task]
Initializes and allocates the SMTPClient_t structure and sets the response sink.
#include <smtp.h>
int smtp_initialize(smtpClient_t ** out_ppSMTP,
smtpSink_t * in_psmtpSink );
The function has the following parameters:
Do not call processResponses after this function.
For more information, see Creating a Client.
smtp_connect, smtpSink_free
[Top] [SMTP Functions] [SMTP Functions by Task]
Initiates sending message; supplies message's reverse path.
#include <smtp.h>
int smtp_mailFrom( smtpClient_t * in_pSMTP,
const char * in_reverseAddress,
const char * in_esmtpParams );
The function has the following parameters:
This function initiates sending the message. The in_reverseAddress parameter supplies the message's reverse path, usually the sender's fully qualified domain name. This function sends the MAIL FROM: SMTP protocol command. For more information, see Setting the Mailer.
NOTE:
Using the ESMTP option DSN requires a detailed understanding of the SMTP
protocol. (Links to RFCs: SMTP RFCs) §
This function is mapped to one or more callbacks in the smtpSink_t.mailFrom, smtpSink_t.error, smtp_rcptTo
[Top] [SMTP Functions] [SMTP Functions by Task]
Gets positive server response.
#include <smtp.h>
int smtp_noop(smtpClient_t * in_pSMTP);
The function has the following parameters:
If you send any command, the server responds with a "still here" response. Sending the smtp_noop function does nothing except force this server response. You can use this function to maintain server connection, perhaps issuing it at timed intervals to make sure that the server is still active.
Your application may not need this function. For example, if the application does something and then disconnects at once, there is no need to make sure that the server is still connected.
This function sends the NOOP SMTP protocol command. It is mapped to one or more callbacks in the smtpSink_t.noop, smtpSink_t.error
[Top] [SMTP Functions] [SMTP Functions by Task]
Processes the server responses for API commands.
#include <smtp.h>
int smtp_processResponses( smtpClient_t * in_pSMTP );
The function has the following parameters:
This function reads in responses from the server. It invokes the callback functions provided by the user for all responses that are available at the time of execution.
If a time-out occurs, the user can continue by calling smtp_processResponses again.
Do not call SMTP_processResponses after these operations: disconnecting, using any of the set functions, or initializing or freeing either the client or the response sink.
smtpSink_t
[Top] [SMTP Functions] [SMTP Functions by Task]
Closes the connection with the server.
#include <smtp.h>
int smtp_quit(smtpClient_t * in_pSMTP);
The function has the following parameters:
This function sends the QUIT SMTP protocol command. Issuing this function ends the session. For more information, see Ending the Session.
This function is mapped to one or more callbacks in the smtpSink_t.quit, smtpSink_t.error
[Top] [SMTP Functions] [SMTP Functions by Task]
Specifies a message recipient's address.
#include <smtp.h>
int smtp_rcptTo( smtpClient_t * in_pSMTP,
const char * in_forwardAddress,
const char * in_esmtpParams );
The function has the following parameters:
This function specifies the address of a message recipient. It is called once for each recipient and should follow the smtp_mailFrom command. For more information, see Setting the Recipient.
This function sends the RCPT TO SMTP protocol command. It is mapped to one or more callbacks in the smtpSink_t.rcptTo, smtpSink_t.error, smtp_mailFrom
[Top] [SMTP Functions] [SMTP Functions by Task]
Resets the state of the server; discards any sender and recipient information.
#include <smtp.h>
int smtp_reset( smtpClient_t * in_pSMTP );
The function has the following parameters:
This function cancels the current mail transfer and resets the state of the server. It sends the RSET SMTP protocol command, causing the server to return to the state that followed the last function that sent the EHLO command.
This function is mapped to one or more callbacks in the smtpSink_t.reset, smtpSink_t.error, smtp_ehlo
[Top] [SMTP Functions] [SMTP Functions by Task]
Sends message data to the server.
#include <smtp.h>
int smtp_send( smtpClient_t * in_pSMTP,
const char * in_data );
The function has the following parameters:
This function sends data in conjunction with smtp_data. Call smtp_data, then call this function. For more information, see Sending the Message.
You can use either the send or sendStream function to deliver data to the server. smtp_send sends data in a single chunk, while smtp_sendStream sends the data in a series of smaller chunks. If you use one of these functions, prepare to send data with smtp_data and not smtp_bdat.
This function is mapped to one or more callbacks in the smtpSink_t.send, smtpSink_t.error,
smtp_bdat, smtp_data, smtp_sendStream
[Top] [SMTP Functions] [SMTP Functions by Task]
Sends an SMTP command that is not otherwise supported by the SDK.
#include <smtp.h>
int smtp_sendCommand( smtpClient_t * in_pSMTP,
const char * in_command);
The function has the following parameters:
You can use this function to extend the protocol to meet your application needs. Using this function, you can extend the functionality of the SDK to meet your needs by adding functions or passing different parameters to a function.
This function is mapped to one or more callbacks in the smtpSink_t.sendCommand,
smtpSink_t.SendCommandComplete,
smtpSink_t.error
[Top] [SMTP Functions] [SMTP Functions by Task]
Sends message data from a stream to the server.
#include <smtp.h>
int smtp_sendStream( smtpClient_t * in_pSMTP,
nsmail_inputstream_t * in_inputStream );
The function has the following parameters:
This function sends data in conjunction with smtp_data. Call smtp_data, then call this function. For more information, see Sending the Message.
You can use either the send or sendStream function to deliver data to the server. smtp_send sends data in a single chunk, while smtp_sendStream sends the data in a series of smaller chunks. If you use one of these functions, prepare to send data with smtp_data and not smtp_bdat.
This function is mapped to one or more callbacks in the smtpSink_t.send, smtpSink_t.error,
smtp_bdat, smtp_data, smtp_send
[Top] [SMTP Functions] [SMTP Functions by Task]
Sets the size of the data chunks to send.
#include <smtp.h>
int smtp_setChunkSize( smtpClient_t * in_pSMTP,
int in_chunkSize );
The function has the following parameters:
This function sets the size of the message data chunks that are read from the input stream and sent to the server. For more information, see Sending the Message.
smtp_sendStream
[Top] [SMTP Functions] [SMTP Functions by Task]
Sets IO models.
#include <smtp.h>
int smtp_set_option( smtpClient_t * in_pSMTP,
int in_option,
void * in_pOptionData );
The function has the following parameters:
To inquire on options set with this function, use smtp_get_option.
NOTE:
Do not call the processResponses function after this function. §
smtp_get_option
[Top] [SMTP Functions] [SMTP Functions by Task]
Attempts to enable pipelining.
#include <smtp.h>
int smtp_setPipelining( smtpClient_t * in_pSMTP,
boolean in_enablePipelining);
The function has the following parameters:
This function attempts to enable or disable pipelining. Pipelining is enabled if the server supports it. If not, the way the network works does not change. This function sends the PIPELINING SMTP protocol command.
Pipelining is a way to batch functions. If enabled, pipelinable functions are stored locally until a specific function triggers the commands to be sent. When triggered by any non-pipelinable function, all functions begin to execute.
The pipelinable functions are smtp_bdat, smtp_mailFrom, smtp_rcptTo, smtp_send, and smtp_sendStream.
You can enable pipelining at any time, but it may make sense to do this immediately after invoking the NOTE:
Do not call the processResponses function after this function. Functions for
which you do not call processResponses: disconnecting, the set functions,
initializing and freeing the client and sink. §
smtp_ehlo,
[Top] [SMTP Functions] [SMTP Functions by Task]
Sets a new response sink.
#include <smtp.h>
int smtp_setResponseSink ( smtpClient_t * in_pSMTP,
smtpSink_t * in_psmtpSink );
The function has the following parameters:
This function overrides the response sink passed into the initialized function.
NOTE:
Do not call the processResponses function after this function. Functions for
which you do not call processResponses: disconnecting, the set functions,
initializing and freeing the client and sink. §
smtpSink_t
[Top] [SMTP Functions] [SMTP Functions by Task]
Sets the amount of time allowed to wait before returning control to the user.
#include <smtp.h>
int smtp_setTimeout( smtpClient_t * in_pSMTP,
double in_timeout );
The function has the following parameters:
This function sets the amount of time, in seconds, allowed to wait before returning control to the user.
NOTE:
Do not call the processResponses function after this function. Functions for
which you do not call processResponses: disconnecting, the set functions,
initializing and freeing the client and sink. §
smtp_processResponses
[Top] [SMTP Functions] [SMTP Functions by Task]
Verifies a user name.
#include <smtp.h>
int smtp_verify( smtpClient_t * in_pSMTP,
const char * in_user );
The function has the following parameters:
This function sends the VRFY SMTP protocol command. It is mapped to one or more callbacks in the smtpSink_t.verify, smtpSink_t.error
[Top] [SMTP Functions] [SMTP Functions by Task]
Frees the SMTP response sink and its data members.
#include <pop3.h>
void smtpSink_free( smtpSink_t ** in_ppsmtp_Sink );
The function has the following parameters:
This function frees the SMTPClient_t structure and its data members. When this function returns, the response sink is set to null. The user must free any opaque data.
NOTE:
Do not call the processResponses function after this function. §
smtp_quit, smtp_free, smtpSink_initialize
[Top] [SMTP Functions] [SMTP Functions by Task]
Initializes and allocates the smtpSink_t structure.
#include <smtp.h>
int smtpSink_initialize( smtpSink_t ** out_ppsmtpSink );
The function has the following parameters:
For more information, see Creating a Response Sink.
NOTE:
Do not call the processResponses function after this function. §
smtp_connect, smtp_noop, smtpSink_free,
smtp_initialize
[Top] [SMTP Functions] [SMTP Functions by Task]
This section defines SMTP data structures, listed in alphabetical order.
[Top] [SMTP Functions]
Represents the SMTP client.
typedef struct smtpClient smtpClient_t;
The client uses this structure to communicate with an SMTP server. The developer uses this structure to perform SMTP API operations. All data contained within the client structure is used internally by the API.
For more information, see Creating a Client.
smtp_initialize, smtp_free
[Top] [SMTP Structures]
Represents the SMTP notification sink.
typedef struct smtpSink
{
void * pOpaqueData;
void (*bdat)( smtpSink_t * in_psmtpSink,
int in_responseCode,
const char * in_responseMessage );
void (*connect)( smtpSink_t * in_psmtpSink,
int in_responseCode,
const char * in_responseMessage );
void (*data)( smtpSink_t * in_psmtpSink,
int in_responseCode,
const char * in_responseMessage );
void (*ehlo)( smtpSink_t * in_psmtpSink,
int in_responseCode,
const char * in_serverExtension );
void (*ehloComplete)(smtpSink_t * in_psmtpSink );
void (*expand)( smtpSink_t * in_psmtpSink,
int in_responseCode,
const char * in_emailAddress );
void (*error)( SMTPSinkPtr_t in_psmtpSink,
int in_responseCode,
const char * in_errorMessage );
void (*expand)( SMTPSinkPtr_t in_psmtpSink,
int in_responseCode,
const char * in_emailAddress );
void (*expandComplete)(smtpSink_t * in_psmtpSink);
void (*help)( smtpSink_t * in_psmtpSink,
int in_responseCode,
const char * in_helpMessage );
void (*helpComplete)(smtpSink_t * in_psmtpSink );
void (*mailFrom)( smtpSink_t * in_psmtpSink,
int in_responseCode,
const char * in_responseMessage );
void (*noop)( smtpSink_t * in_psmtpSink,
int in_responseCode,
const char * in_responseMessage );
void (*quit)( smtpSink_t * in_psmtpSink,
int in_responseCode,
const char * in_responseMessage );
void (*rcptTo)( smtpSink_t * in_psmtpSink,
int in_responseCode,
const char * in_responseMessage );
void (*reset)( smtpSink_t * in_psmtpSink,
int in_responseCode,
const char * in_responseMessage );
void (*send)( smtpSink_t * in_psmtpSink,
int in_responseCode,
const char * in_responseMessage );
void (*sendCommand)( smtpSink_t * in_psmtpSink,
int in_responseCode,
const char * in_responseMessage );
void (*sendCommandComplete)(smtpSink_t *
in_psmtpSink );
void (*verify)( smtpSink_t * in_psmtpSink,
int in_responseCode,
const char * in_responseMessage );
}smtpSink_t;
The structure has the following fields:
void * pOpaqueData; |
User data.
|
void (*bdat)(
SMTPSinkPtr_t in_psmtpSink,
int in_responseCode,
const char * in_responseMessage ); |
Notification for the response to the BDAT command. Parameters: the response sink to use, the SMTP response code, and descriptive response message.
|
void (*connect)(
SMTPSinkPtr_t in_psmtpSink,
int in_responseCode,
const char * in_responseMessage ); |
Notification for the response to the connection to the server. Parameters: the response sink to use, the SMTP response code, and descriptive response message.
|
void (*data)(
SMTPSinkPtr_t in_psmtpSink,
int in_responseCode,
const char * in_responseMessage ); |
Notification for the response to the DATA command. Parameters: the response sink to use, the SMTP response code, and descriptive response message.
|
void (*ehlo)(
SMTPSinkPtr_t in_psmtpSink,
int in_responseCode,
const char * in_serverExtension ); |
Notification for the response to the EHLO command. Parameters: the response sink to use, the SMTP response code, and descriptive response message.
|
void (*ehloComplete)(
SMTPSinkPtr_t in_psmtpSink ); |
Notification for the completion of the EHLO command. Parameter: response sink to use.
|
void (*error)(
SMTPSinkPtr_t in_psmtpSink,
int in_responseCode,
const char * in_errorMessage ); |
Notification for an error. Parameters: the response sink to use, the SMTP response code, and descriptive response message.
|
void (*expand)(
SMTPSinkPtr_t in_psmtpSink,
int in_responseCode,
const char * in_emailAddress ); |
Notification for the response to the EXPN command. Parameters: the response sink to use, the SMTP response code, and descriptive response message.
|
void (*expandComplete)(
SMTPSinkPtr_t in_psmtpSink); |
Notification for the completion of the EXPN command. Parameter: response sink for this client.
|
void (*help)(
SMTPSinkPtr_t in_psmtpSink,
int in_responseCode,
const char * in_helpMessage ); |
Notification for the response to the HELP command. Parameters: the response sink to use, the SMTP response code, and descriptive response message.
|
void (*helpComplete)(
SMTPSinkPtr_t in_psmtpSink ); |
Notification for the completion of the HELP command. Parameters: the response sink to use.
|
void (*mailFrom)(
SMTPSinkPtr_t in_psmtpSink,
int in_responseCode,
const char * in_responseMessage ); |
Notification for the response to the MAIL FROM command. Parameters: the response sink to use, the SMTP response code, and descriptive response message.
|
void (*noop)(
SMTPSinkPtr_t in_psmtpSink,
int in_responseCode,
const char * in_responseMessage ); |
Notification for the response to the NOOP command. Parameters: the response sink to use, the SMTP response code, and descriptive response message.
|
void (*quit)(
SMTPSinkPtr_t in_psmtpSink,
int in_responseCode,
const char * in_responseMessage ); |
Notification for the response to the QUIT command. Parameters: the response sink to use, the SMTP response code, and descriptive response message.
|
void (*rcptTo)(
SMTPSinkPtr_t in_psmtpSink,
int in_responseCode,
const char * in_responseMessage ); |
Notification for the response to the RCPT TO command. Parameters: the response sink to use, the SMTP response code, and descriptive response message.
|
void (*reset)(
SMTPSinkPtr_t in_psmtpSink,
int in_responseCode,
const char * in_responseMessage ); |
Notification for the response to the RSET command. Parameters: the response sink to use, the SMTP response code, and descriptive response message.
|
void (*send)(
SMTPSinkPtr_t in_psmtpSink,
int in_responseCode,
const char * in_responseMessage ); |
Notification for the response to data sent to the server. Parameters: the response sink to use, the SMTP response code, and descriptive response message.
|
void (*sendCommand)(
SMTPSinkPtr_t in_psmtpSink,
int in_responseCode,
const char * in_responseMessage ); |
Notification for the response to sendCommand function. Parameters: the response sink to use, the SMTP response code, and descriptive response message.
|
void (*sendCommandComplete)
(SMTPSinkPtr_t in_psmtpSink ); |
Notification for the completion of the extended command. Parameters: the response sink to use.
|
void (*verify)(
SMTPSinkPtr_t in_psmtpSink,
int in_responseCode,
const char * in_responseMessage ); |
Notification for the response to the VRFY command. Parameters: the response sink to use, the SMTP response code, and descriptive response message.
|
The SMTP response sink structure is made up of function pointers and opaque data. You must define the functions yourself, and you must point these pointers to your functions if you want to receive the related server responses. For more information, see SDK Response Sinks for C and Creating a Response Sink.
The function pointers serve as callbacks for many SMTP functions. See SMTP Function Callback Mapping.
smtp_setResponseSink, smtpSink_initialize,
smtpSink_free
[Top] [SMTP Structures]
Table of Contents | Previous
| Next
| Index
Last Updated: June 3, 1998
Copyright © 1998
Netscape Communications Corporation