tfSmtpUserReadTimer

Table of Contents >> Optional Protocols >> SMTP

#include <trsocket.h>

long tfSmtpUserReadTimer

(ttSmtpClientHandle smtpClientHandle);

Function Description

If you are running a non-blocking SMTP client, you can call this function to determine when a client-side timeout is due to occur. Timing is active only when waiting for a response from the server, e.g. after connecting or issuing a command. The timer is not active when the session is idle and waiting for user action. The timeout value is specified when you call tfSmtpUserNewSession().

If the timer is active, the non-negative number of milliseconds remaining in the timeout interval is returned. If the interval has expired, 0 is returned. If the timer is not active, -1 is returned.

In a non-blocking client, timeout events are detected and serviced during your tfSmtpUserExecute() call. If you call tfSmtpUserExecute() at regular intervals, socket events and timeout events will be handled automatically. The responsiveness to those events depends on the resolution of your timing interval.

If you choose to base your tfSmtpUserExecute() calls on the SMTP asynchronous event callback (see Performance concerns when using non-blocking mode) instead of a regular timing interval, you can achieve better TCP responsiveness but you will lose your client timeout responsiveness (your timeout alert comes from your tfSmtpUserExecute() call).

To get around this conundrum, call tfSmtpUserReadTimer() to obtain an upper limit on how long to wait for a signal from your asynchronous event callback. The following is an example of how you could combine tfSmtpUserReadTimer() with asynchronous events.

void mySmtpClient(void)
{
    ttSmtpClientHandle mySmtpClientHandle;
    long               msec;
    int                errorCode;
      . . .
    mySmtpClientHandle = tfSmtpUserNewSession( . . . );
      . . .
    errorCode = tfSmtpUserSetAsyncCB(mySmtpClientHandle, mySmtpAsyncNotify);
      . . .
    errorCode = tfSmtpUserConnect( . . . );
      . . .
    while (!finished)
    {
        msec = tfSmtpUserReadTimer(mySmtpClientHandle);
        if (msec > 0)
        {
/* An operation is in progress; wait for async signal or timeout */
            KernelWait(mySmtpAsyncSemaphore, msec);
        }
        else if (msec != 0)
        {
/* No operation is in progress or has expired; sleep for 1 second */
            sleep(1000L);
        }
/* Service pending events */
        errorCode = tfSmtpUserExecute(mySmtpClientHandle);
          . . .
    }
      . . .
}
 
/*
 * Receive SMTP socket events (received data, remote close) and alert the main thread.
 */
void mySmtpAsyncNotify(
    ttSmtpClientHandle  smtpClientHandle,
    void TM_FAR *       userPtr,
    int                 eventId)
{
    KernelSignal(mySmtpAsyncSemaphore);
}

Parameters

• smtpClientHandle

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

Returns

• >0

  The time remaining, in milliseconds, in the timeout interval of the operation that is currently in progress and waiting for server response.

• 0

  The operation that is currently in progress has reached its timeout limit.

• <0

  The timer is inactive (e.g. waiting for the next user command) or the specified handle is invalid.

Table of Contents >> Optional Protocols >> SMTP