Async Server Messaging Functions

Functions
MOC_EXTERN sbyte4	SSH_ASYNC_ackReceivedMessageBytes (sbyte4 connectionInstance, enum sshSessionTypes sessionEvent, ubyte4 numBytesAck)
	Send an acknowledgement that data was received by the server. More...
MOC_EXTERN sbyte4	SSH_ASYNC_recvContinueMessage (sbyte4 connectionInstance, sbyte4 result)
	Resume (continue) an authentication process that was waiting for a result. More...
MOC_EXTERN sbyte4	SSH_ASYNC_recvMessage (sbyte4 connectionInstance, ubyte *pBytesReceived, ubyte4 numBytesReceived)
	Get data from a client. More...
MOC_EXTERN sbyte4	SSH_ASYNC_sendMessage (sbyte4 connectionInstance, sbyte *pBuffer, sbyte4 bufferSize, sbyte4 *pBytesSent)
	Send data to a client. More...
MOC_EXTERN sbyte4	SSH_ASYNC_sendMessagePending (sbyte4 connectionInstance, ubyte4 *pRetNumBytesPending)
	Determine whether there is data in a connection instance's SSH send buffer. More...

Detailed Description

Function Documentation

SSH_ASYNC_ackReceivedMessageBytes()

MOC_EXTERN sbyte4 SSH_ASYNC_ackReceivedMessageBytes	(	sbyte4	connectionInstance,
		enum sshSessionTypes	sessionEvent,
		ubyte4	numBytesAck
	)

This function sends an acknowledgement that data was received by the server on the specified connection. Your application must explicitly call this function; there is no automatic acknowledgement.

Important Digicert NanoSSH server versions earlier than 1.41 automatically acknowledged received data. Therefore, if you're porting your application from an earlier NanoSSH server version, be sure to add calls to this function.

Since

1.41

Version

1.41 and later

To enable this function, the following flag must be defined in moptions.h:

• __ENABLE_MOCANA_SSH_ASYNC_SERVER_API__

Parameters

connectionInstance	Connection instance returned from SSH_ASYNC_acceptConnection().
sessionEvent	Type of message for which data was received (an sshSessionTypes enumerated value, defined in ssh.h).
numBytesAck	Number of bytes received.

ssh.h

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

Remarks

This function is applicable to asynchronous servers.

ssh.h

SSH_ASYNC_recvContinueMessage()

MOC_EXTERN sbyte4 SSH_ASYNC_recvContinueMessage	(	sbyte4	connectionInstance,
		sbyte4	result
	)

This function resumes (continues) an authentication process that was waiting for a result from an authentication server.

Since

1.41

Version

1.41 and later

To enable this function, the following flag must be defined in moptions.h:

• __ENABLE_MOCANA_SSH_ASYNC_SERVER_API__

ssh.h

Parameters

connectionInstance	Connection instance returned from SSH_ASYNC_acceptConnection().
result	Result of previous authentication attempt; see ssh_auth_result_codes.

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

Remarks

This function is applicable to asynchronous servers.

ssh.h

SSH_ASYNC_recvMessage()

MOC_EXTERN sbyte4 SSH_ASYNC_recvMessage	(	sbyte4	connectionInstance,
		ubyte *	pBytesReceived,
		ubyte4	numBytesReceived
	)

This function retrieves data from a client. It should be called from your TCP/IP receive upcall handler, or from your application after reading a packet of data. The engine decrypts and processes the packet, and then calls the sshSettings::funcPtrReceivedData upcall to handle the decrypted data.

Since

1.41

Version

1.41 and later

To enable this function, the following flag must be defined in moptions.h:

• __ENABLE_MOCANA_SSH_ASYNC_SERVER_API__

Parameters

connectionInstance	Connection instance returned from SSH_ASYNC_acceptConnection().
pBytesReceived	Pointer to the packet or message received from the TCP/IP stack.
numBytesReceived	Number of bytes in packet or message received (pBytesReceived).

ssh.h

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

Remarks

This function is applicable to asynchronous servers.

// ...

    while ((OK == status) && (TRUE != mBreakServer))
    {
        if (OK <= (status = TCP_READ_AVL(socketClient,
                                         pInBuffer,
                                         SSH_SYNC_BUFFER_SIZE,
                                         &numBytesRead,
                                         20000)))
        {
            if (0 != numBytesRead)
                status = SSH_ASYNC_recvMessage(connInstance,
                                               pInBuffer,
                                               numBytesRead);
        }

        if (ERR_TCP_READ_TIMEOUT == status)
            status = OK;
    }

// ...

ssh.h

SSH_ASYNC_sendMessage()

MOC_EXTERN sbyte4 SSH_ASYNC_sendMessage	(	sbyte4	connectionInstance,
		sbyte *	pBuffer,
		sbyte4	bufferSize,
		sbyte4 *	pBytesSent
	)

This function sends data to a client. It should not be called until an open shell upcall notification (sshSettings::funcPtrOpenShell).

Since

1.41

Version

1.41 and later

To enable this function, the following flag must be defined in moptions.h:

• __ENABLE_MOCANA_SSH_ASYNC_SERVER_API__

Parameters

connectionInstance	Connection instance returned from SSH_ASYNC_acceptConnection().
pBuffer	Pointer to the send data buffer.
bufferSize	Number of bytes in send data buffer (pBuffer).
pBytesSent	On return, pointer to the number of bytes successfully sent.

ssh.h

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

Remarks

This function is applicable to asynchronous servers.

static void SSH_EXAMPLE_helloWorld(int connectionInstance)
{
    sbyte4 bytesSent = 0;
    sbyte4 status;

    status = SSH_ASYNC_sendMessage(connInstance,
                                   "hello world!", 12,
                                   &bytesSent);
}

ssh.h

SSH_ASYNC_sendMessagePending()

MOC_EXTERN sbyte4 SSH_ASYNC_sendMessagePending	(	sbyte4	connectionInstance,
		ubyte4 *	pRetNumBytesPending
	)

This function determines whether there is data in a connection instance's SSH send buffer. If the send buffer is empty, zero (0) is returned through the pRetNumBytesPending parameter. If send data is pending, an attempt is made to send the data, and the subsequent number of bytes remaining to be sent is returned through the pRetNumBytesPending parameter.

Since

1.41

Version

1.41 and later

To enable this function, the following flag must be defined in moptions.h:

• __ENABLE_MOCANA_SSH_ASYNC_SERVER_API__

Parameters

connectionInstance	Connection instance returned from SSH_ASYNC_acceptConnection().
pRetNumBytesPending	On return, pointer to number of bytes remaining in the send buffer.

ssh.h

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

Note

This function should not be called until after SSH_ASYNC_acceptConnection().

Remarks

This function is applicable to asynchronous servers.

ssh.h