NSSLRead

Syntax

#include <cafe.h>
#include <cafe/nssl/nsslclient.h>

NSSL_RVAL NSSLRead(NSSLConnectionHandle connection,
                   void* pBuf,
                   int len,
                   int* pBytesRead);

Parameters

connection A handle to a SSL connection from which to read.
pBuf Buffer to read into. The buffer size and address should be aligned to NSSL_IO_BUFFER_ALIGN.
len Number of bytes to read.
pBytesRead A pointer to hold the count of bytes read.

Return Values

NSSL_RVAL_OK Success.
NSSL_RVAL_ZERO_RETURN The SSL connection has been closed.
NSSL_RVAL_WANT_READ/NSSL_RVAL_WANT_WRITE (Only applicable for non-blocking connections) The operation did not complete; the same NSSL I/O function should be called again later. If, by then, the underlying socket has data available for reading (if the result code is NSSL_RVAL_WANT_READ) or allows writing data (NSSL_RVAL_WANT_WRITE), then some TLS/SSL protocol progress will take place, i.e., at least part of a TLS/SSL record will be read or written. The retry may again lead to an NSSL_RVAL_WANT_READ or NSSL_RVAL_WANT_WRITE condition. There is no fixed upper limit for the number of iterations that may be necessary until progress becomes visible at application protocol level.
NSSL_RVAL_IO_ERROR Some IO error occurred on the underlying socket.
NSSL_RVAL_NSSLLIB_ERROR A failure in the SSL library occurred.

Description

Reads from the SSL connection. The count of bytes read is written into pBytesRead when completed.

NSSLRead must read an entire record from the underlying socket before it can decrypt it and return it to the application. NSSLRead may return only a portion of a single record but will never return portions of two different records.

If NSSLGetPending returns more than zero, NSSLRead will return at least a portion of the record and will not read additional data from the socket. If NSSLGetPending returns zero, NSSLRead has finished giving the current record to the application and may (but not necessarily) read additional data from the underlying socket at its next call.

Do Not Call From

Callbacks Do not call this function from any callback function.
Interrupt handler Do not call this function from any interrupt handler.
Exception handler Do not call this function from any exception handler.

See Also

NSSLWrite
NSSLGetPending

Revision History

2012/08/16 Cleanup pass.
2012/04/06 Initial version.


CONFIDENTIAL