tfSmtpUserSetSessionOption

Table of Contents >> Optional Protocols >> SMTP

#include <trsocket.h>

int tfSmtpUserSetSessionOption	(
	ttSmtpClientHandle smtpClientHandle,
	int optionName,
	ttUser32Bit optionValue
	);

Function Description

This function sets the SMTP session options. The user can set options at anytime. For example, the user can specify different timeout values for different API calls.

Parameters

• smtpClientHandle

  The SMTP client session handle as returned by tfSmtpUserNewSession().

• optionName

  The name of the option to set (see below).

• optionValue

  The value of the option to set (see below).

Returns

• TM_ENOERROR

  Success.

• TM_EINVAL

  Invalid SMTP client session handle, option name or option value.

• TM_EPERM

  The option must be set prior to calling tfSmtpUserConnect().

SMTP Session Options

Option Name	Option Value
TM_SMTP_OPT_TIMEOUT	This value must be >0.
TM_SMTP_OPT_TLSMODE	SMTP over SSL: Set the method by which the Treck SMTP client will negotiate SSL/TLS with the SMTP server. You must enable SMTP over SSL by defining macro TM_USE_SMTP_SSL in trsystem.h. You must also obtain an SSL session identifier by calling tfSslNewSession() (see the SSL Programmer's Reference) and attach the SSL session identifier to the SMTP session by calling tfSmtpUserSetSsl(). See section SMTP Security Modes below for a description of option values.
TM_SMTP_OPT_AUTHMODE	Set the method by which the Treck SMTP client will provide login credentials. See section SMTP Authentication Modes below for a description of option values.

SMTP Security Modes (Option TM_SMTP_OPT_TLSMODE)

Option Value	Description
TM_SMTP_TLSMODE_OPTIONAL	Begin SSL/TLS negotiations only if the SMTP server advertises support for the STARTTLS command. If the server supports explicit Transport Layer Security, it will list the STARTTLS keyword in the initial EHLO response. This is the default.
TM_SMTP_TLSMODE_ALWAYS	Always attempt explicit SSL/TLS negotiations, even if the SMTP server does not advertise support for the STARTTLS command. Use this mode when you unconditionally require a secure SMTP session if, for example, you need to send login credentials and you do not wish to send them in plaintext. This mode will thwart a man-in-the-middle attack that strips the STARTTLS keyword from the server's EHLO response.
TM_SMTP_TLSMODE_IMPLICIT	Unconditionally begin SSL/TLS negotiations immediately after connecting with the SMTP server. This is known as implicit SSL/TLS. It is a non-standard mode of operation that was mentioned in Appendix A of the The SSL Protocol Version 3.0 for specific use with servers that accept SMTP connections on port 465.

SMTP Authentication Modes (Option TM_SMTP_OPT_AUTHMODE)

Option Value	Description
TM_SMTP_AUTHMODE_UNSECURE	Send authentication credentials in plaintext, if necessary. You must provide your username and password when calling tfSmtpUserConnect(). This is the default if SMTP over SSL is not used.
TM_SMTP_AUTHMODE_SECURE	Send authentication credentials only if the SMTP session is secure (i.e. SSL/TLS negotiations with the server have succeeded). You must provide your username and password when calling tfSmtpUserConnect() and you must enable SMTP over SSL and provide a valid SSL session identifier. This is the default if you have enabled SMTP over SSL and supplied a valid SSL session identifier.

Table of Contents >> Optional Protocols >> SMTP