SMTPc_Connect()

Connect to a SMTP server.

Files

smtp-c.h/smtp-c.c

Prototype

NET_SOCK_ID SMTPc_Connect (CPU_CHAR                *p_host_name,
						   CPU_INT16U               port,
 						   CPU_CHAR                *p_username,
						   CPU_CHAR                *p_pwd,
 						   NET_APP_SOCK_SECURE_CFG *p_secure_cfg,
 						   SMTPc_ERR               *p_err);

Arguments

p_host_name        

Pointer to host name of the SMTP server to connect. Can be also an IP address.

port                        

TCP port to use, or '0' if SMTPc_DFLT_PORT.

p_username          

Pointer to user name, if authentication enabled.

p_pwd                    

Pointer to password, if authentication enabled.

p_secure_cfg        

Pointer to the secure configuration (TLS/SSL).

p_err                      

 Pointer to variable that will receive the return error code from this function.

Returned Values

If the connect operation with the SMTP server is successful, the function will return the Socket descriptor/handle identifier associated to this connection.

If the connect operation with the SMTP server is unsuccessful, the function will return -1.

Required Configuration

Module Configuration.

Notes / Warnings

  1. Network security manager MUST be available & enabled to initialize the server insecure mode.

  2. If anything goes wrong while trying to connect to the server, the socket is closed by calling NetSock_Close. Hence, all data structures are returned to their original state in case of a failure to establish the TCP connection. If the failure occurs when initiating the session, the application is responsible of the appropriate action(s) to be taken.

  3.  If authentication is disabled (SMTPc_CFG_AUTH_EN set to DEF_ENABLED), the 'p_username' and 'p_pwd' parameters should be passed a NULL pointer.

  4. The server will send a 220 "Service ready" reply when the connection is completed. The SMTP protocol allows a server to formally reject a transaction while still allowing the initial connection by responding with a 554 "Transaction failed" reply.

  5. The Plain-text (PLAIN) authentication mechanism is implemented here. However, it takes some liberties from RFC #4964, section 4 'The AUTH Command', stating the "A server implementation MUST implement a configuration in which it does not permit any plaintext password
     mechanisms, unless either the STARTTLS command has been negotiated or some other mechanism that protects the session from password snooping has been provided". Since this client does not support SSL or TLS, or any other protection against password snooping, it relies on the server NOT to fully follow RFC #4954 in order  to be successful.

  6. To resolve the SMTP server adress with it name domain, be sure that µC/DNSc has been correctly initialized.  

Example Usage

none.