Sync Server Messaging Functions

Functions
MOC_EXTERN sbyte4	SSH_recv (sbyte4 connectionInstance, sbyte4 *pMessageType, ubyte *pRetBuffer, ubyte4 bufferSize, sbyte4 *pNumBytesReceived, ubyte4 timeout)
	Get data from a server and decrypt the data. More...
MOC_EXTERN sbyte4	SSH_recvMessage (sbyte4 connectionInstance, sbyte4 *pMessageType, sbyte *pRetMessage, sbyte4 *pNumBytesReceived, ubyte4 timeout)
	Get an entire message from a server and decrypt the data. More...
MOC_EXTERN sbyte4	SSH_recvPending (sbyte4 connectionInstance, sbyte4 *pRetBooleanIsPending)
	Determine whether there is data in a connection instance's SSH receive buffer. More...
MOC_EXTERN sbyte4	SSH_sendErrMessage (sbyte4 connectionInstance, sbyte *pBuffer, sbyte4 bufferSize, sbyte4 *pBytesSent)
	Send stderr error message output data over SSH. More...
MOC_EXTERN sbyte4	SSH_sendMessage (sbyte4 connectionInstance, sbyte *pBuffer, sbyte4 bufferSize, sbyte4 *pBytesSent)
	Send data to a client. More...

Detailed Description

Function Documentation

SSH_recv()

MOC_EXTERN sbyte4 SSH_recv	(	sbyte4	connectionInstance,
		sbyte4 *	pMessageType,
		ubyte *	pRetBuffer,
		ubyte4	bufferSize,
		sbyte4 *	pNumBytesReceived,
		ubyte4	timeout
	)

This function retrieves data from a server, decrypts the data, and stores it in the provided buffer. The retrieved data may be the full message or only part of the message.

In contrast to SSH_recvMessage(), which reads an entire message, this function enables streaming data reads of just part of a message.

Since

1.41

Version

1.41 and later

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

• __ENABLE_MOCANA_SSH_SERVER__
• __ENABLE_MOCANA_SSH_STREAM_API__

Additionally, the following flag must not be defined:

• __ENABLE_MOCANA_SSH_ASYNC_SERVER_API__

Parameters

connectionInstance	Connection instance returned from SSH_acceptConnection().
pMessageType	On return, pointer to type of message received (an sshSessionTypes enumerated value, defined in ssh.h).
pRetBuffer	Pointer to receive message buffer.
bufferSize	Number of bytes in receive message buffer (pRetBuffer).
pNumBytesReceived	On return, pointer to the number of bytes received.
timeout	Number of milliseconds for the client to wait to receive the message; 0 specifies no timeout (an infinite wait).

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 an SSH connection is established between the client and server; otherwise an error is returned.

Remarks

This function is applicable to synchronous servers.

ssh.h

SSH_recvMessage()

MOC_EXTERN sbyte4 SSH_recvMessage	(	sbyte4	connectionInstance,
		sbyte4 *	pMessageType,
		sbyte *	pRetMessage,
		sbyte4 *	pNumBytesReceived,
		ubyte4	timeout
	)

This function retrieves an entire message from a server, decrypts the data, and stores it in the provided buffer.

In contrast to SSH_recv(), which reads just part of a message, this function reads an entire message at once.

Since

1.41

Version

1.41 and later

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

• __ENABLE_MOCANA_SSH_SERVER__

Additionally, the following flags must not be defined:

• __ENABLE_MOCANA_SSH_ASYNC_SERVER_API__
• __ENABLE_MOCANA_SSH_STREAM_API__

Parameters

connectionInstance	Connection instance returned from SSH_acceptConnection().
pMessageType	On return, pointer to type of message received (an sshSessionTypes enumerated value, defined in ssh.h).
pRetMessage	Pointer to receive message buffer.
pNumBytesReceived	On return, pointer to the number of bytes received.
timeout	Number of milliseconds for the client to wait to receive the message; 0 specifies no timeout (an infinite wait).

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 must not be called until an SSH connection is established between the client and server; otherwise an error is returned.

Remarks

This function is applicable to synchronous servers.

static void SSH_EXAMPLE_simpleCLI(sbyte4 connectionInstance)
{
    ubyte*     pInBuffer = NULL;         // incoming data
    sbyte4     numBytesReceived;
    sbyte4     mesgType = 0;
    sbyte4     bytesSent, status;

    if (0 > (status = SSH_negotiateConnection(connInstance)))    // key xchange
        goto exit;

    if (NULL == (pInBuffer = malloc(MAX_SESSION_WINDOW_SIZE)))  // alloc rx buffer
        goto exit;

    while ((0 <= status) && ((sbyte4)SSH_SESSION_EOF > mesgType))
    {   // echo msg
        status = SSH_recvMessage(connectionInstance, &mesgType,
                                 pInBuffer, &numBytesReceived, 0);
    if ((0 <= status) && (SSH_SESSION_DATA == mesgType))
            status = SSH_sendMessage(connectionInstance, pInBuffer,
                                     numBytesReceived, &bytesSent)))
    }
exit: // cleanup
    return;
}

ssh.h

SSH_recvPending()

MOC_EXTERN sbyte4 SSH_recvPending	(	sbyte4	connectionInstance,
		sbyte4 *	pRetBooleanIsPending
	)

This function determines whether there is data in a connection instance's SSH receive buffer, and returns the result (TRUE or FALSE) through the pRetBooleanIsPending parameter.

Since

1.41

Version

1.41 and later

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

• __ENABLE_MOCANA_SSH_SERVER__
• __ENABLE_MOCANA_SSH_STREAM_API__

Additionally, the following flag must not be defined:

• __ENABLE_MOCANA_SSH_ASYNC_SERVER_API__

Parameters

connectionInstance	Connection instance returned from SSH_acceptConnection().
pRetBooleanIsPending	On return, pointer to TRUE if there is data to be received; otherwise pointer to FALSE.

Remarks

This function is applicable to synchronous servers.

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.

ssh.h

SSH_sendErrMessage()

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

This function sends stderr error message output data over SSH.

Since

1.41

Version

1.41 and later

To enable this function, at least one of the following flags must be defined in moptions.h:

• __ENABLE_MOCANA_SSH_SERVER__
• __ENABLE_MOCANA_SSH_ASYNC_SERVER_API__

Parameters

connectionInstance	Connection instance returned from SSH_acceptConnection().
pBuffer	Pointer to buffer containing the stderr error message data to send.
bufferSize	Number of bytes in the error message (bBuffer).
pBytesSent	On return, pointer to 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 synchronous and asynchronous servers.

ssh.h

SSH_sendMessage()

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

This function sends data to a server unless deadlock prevention is enabled by the ENABLE_MOCANA_SSH_SENDER_RECV flag and the SSH transport window size indicates insufficient client acknowledgement of previously sent data.

Note

This function should not be called until an SSH client-server connection is established.

Since

1.41

Version

1.41 and later

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

• __ENABLE_MOCANA_SSH_SERVER__

Additionally, the following flag must not be defined:

• __ENABLE_MOCANA_SSH_ASYNC_SERVER_API__

Parameters

connectionInstance	Connection instance returned from SSH_acceptConnection().
pBuffer	Pointer to the buffer containing the data to send.
bufferSize	Number of bytes in the send data buffer (pBuffer).
pBytesSent	On return, pointer to 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 synchronous servers.

static void SSH_EXAMPLE_simpleCLI(sbyte4 connectionInstance)
{
    // incoming data
    ubyte*   pInBuffer = NULL;
    sbyte4     numBytesReceived;
    sbyte4     mesgType = 0;
    sbyte4     bytesSent;
    sbyte4     status;

    if (0 > (status = SSH_negotiateConnection(connInstance)))   // do key xchange
        goto exit;

    if (NULL == (pInBuffer = malloc(MAX_SESSION_WINDOW_SIZE)))   // alloc rx buffer
        goto exit;

    // echo message back to client
    while ((0 <= status) && ((sbyte4)SSH_SESSION_EOF > mesgType))
    {
        status = SSH_recvMessage(connectionInstance, &mesgType,
                                 pInBuffer, &numBytesReceived, 0);

        if ((0 <= status) && (SSH_SESSION_DATA == mesgType))
            status = SSH_sendMessage(connectionInstance, pInBuffer,
                                     numBytesReceived, &bytesSent)))
    }

exit:
    // cleanup
    return;
}

ssh.h