IMAPConnect

Syntax

IMAPConnect (server,username,password[,stsproc,responselist,secure {Default zero insecure;1 secure;2 use STARTTLS},verify {Default kTrue}]) Returns socket

Description

Note: The flag is set according to whether Omnis was able to make a call to this external command.

This Web command is multi-threaded, allowing another thread to execute in the multi-threaded server while it runs. Note that the same socket cannot safely be used concurrently by more than one thread.

IMAPConnect establishes a connection with an IMAP server. The server must support IMAP4rev1. See RFC 3501 for details. If IMAPConnect succeeds, it returns the socket opened to the IMAP server. You can use this socket with the other IMAP commands which require a socket argument. If an error occurs, IMAPConnect returns an error code, which is less than zero. Possible error codes are listed in the Web Command Error Codes Appendix.

Note that it is essential that you call IMAPDisconnect when you have finished using the connection to the IMAP server.

Server is an Omnis Character field containing the IP address or hostname of an IMAP server. For example: imap.mydomain.com or 255.255.255.254. If the server is not using the default IMAP port (143, or 993 for a secure connection), you can optionally append the port number on which the server is listening, using the syntax server:port, for example imap.mydomain.com:1234.

Username is an Omnis Character field containing the user name that will be used to log in to the IMAP server. The command uses CRAM-MD5 authentication if possible; if CRAM-MD5 is not supported by the server, or fails to authenticate for some reason, the command uses the plain text LOGIN command if the server allows it.

Password is an Omnis character field containing the password for the user specified by the username parameter.

Stsproc is an optional parameter containing the name of an Omnis method that this command calls with status messages. This command calls the method with no parameters, and the status information in the variable #S1. The status information logs protocol messages exchanged on the connection to the server.

Responselist is an optional parameter into which this command places response lines received from the IMAP server. Before calling this command, define the responselist to have a single Character column. When the command returns successfully, the response list contains the untagged and tagged responses received from the IMAP server as a result of executing this command. These sometimes include unsolicited information, for example, an update on the current number of messages in the selected mailbox. Each line in the response list is a response line received from the server. See RFC 3501 for more details, if you need to handle this sort of information. Note you can only omit responselist if it would be the last parameter to be sent, therefore if you include secure and/or verify, then responselist must be included.

Secure is an optional Boolean parameter which indicates if a secure connection is required to the server. Pass kTrue for a secure connection, in which case the built-in security technology will be used, so on Windows ‘Secure Channel’ (Schannel) is used, on macOS ‘Secure Transport’ is used, and on Linux OpenSSL is used.

IMAPConnect also supports an alternative secure option, if you pass secure with the value 2, the connection is initially not secure, but after the initial exchange with the server, IMAPConnect issues a STARTTLS IMAP command to make the connection secure if the server supports it (see RFC 3501 for details). Authentication occurs after a successful STARTTLS command.

Verify is an optional Boolean parameter which is only significant when Secure is not kFalse. When Verify is kTrue, the command instructs the installed SSL library to verify the server's identity using its certificate; if the verification fails, then the connection will not be established. You can pass Verify as kFalse, to turn off this verification; in this case, the connection will still be encrypted, but there is a chance the server is an impostor. In order to perform the verification, the installed SSL library uses the Certificate Authority Certificates in the cacerts sub-folder of the secure folder in the Omnis folder. If you use your own Certificate Authority to self-sign certificates, you can place its certificate in the cacerts folder, and the installed SSL library will use it after you restart Omnis.

Example

# Establish a connection to the IMAP server lServer for user
# lUsername using the password lPassword 
Calculate lServer as  'my.imap.server'
Calculate lUserName as  'myusername'
Calculate lPassword as  'mypassword'
IMAPConnect (lServer,lUserName,lPassword) Returns iIMAPSocket
If  iIMAPSocket<0
  # Connection failed 
End If