SSL_Write()--Write Data to an SSL-Enabled Socket Descriptor

 #include <qsossl.h>

 int SSL_Write(SSLHandle *handle,   
               void *buffer,
               int buffer_length)

The SSL_Write() function is used by a program to write data to an SSL-enabled socket descriptor.

Parameters

SSLHandle* handle  (input) 

The pointer to an SSLHandle for an SSL session. An SSLHandle is a typedef for a buffer of type struct SSLHandleStr. In <qsossl.h>, struct SSLHandleStr is defined as the following:

struct SSLHandleStr { /* SSLHandleStr */ int fd; /* Socket descriptor */ int createFlags; /* SSL_Create flags value */ unsigned protocol; /* SSL protocol version */ unsigned timeout; /* Timeout value in seconds */ unsigned char cipherKind[3]; /* Current 2.0 cipher suite*/ unsigned short int cipherSuite; /* Current 3.0 cipher suite */ unsigned short int* cipherSuiteList; /* List of cipher suites */ unsigned int cipherSuiteListLen; /* Number of entries in the cipher suites list */ unsigned char* peerCert; /* Peer certificate */ unsigned peerCertLen; /* Peer certificate length */ int peerCertValidateRc; /* Return code from validation of certficate */ int (*exitPgm)(struct SSLHandleStr* sslh); /* Authentication exit program called when a certificate is received during SSL handshake */ };

void *buffer  (input) 

A pointer to the user-supplied buffer in which the data to be written is stored.

int buffer_length  (input) 

The length of the buffer.

Authorities

No authorization is required.

Return Value

SSL_Write() returns an integer. Possible values are:

[n]

Successful, where n is the number of bytes written.

[SSL_ERROR_BAD_STATE]

SSL detected a bad state in the SSL session.

[SSL_ERROR_CLOSED]

The SSL session ended.

[SSL_ERROR_IO]

An error occurred in SSL processing; check the errno value.

[SSL_ERROR_UNKNOWN]

An unknown or unexpected error occurred during SSL processing.

Error Conditions

When the SSL_Write() API fails with return code [SSL_ERROR_IO], errno can be set to to one of the following:

[EBADF]

Descriptor not valid.

[EFAULT]

Bad address.

One of the following conditions occurred:

• The system detected an address that was not valid while attempting to access the buffer parameter.
• The system detected an address that was not valid while attempting to access the handle parameter or one of the address fields in the handle parameter.

[EINTR]

Interrupted function call.

[EINVAL]

Parameter not valid.

This error code indicates one of the following:

• The socket_descriptor type is not SOCK_STREAM or address family is not AF_INET or AF_INET6.
• One of the parameters passed is not valid or is NULL.
• The buffer_length parameter specifies a negative value.

[EIO]

Input/output error.

[ENOBUFS]

There is not enough buffer space for the requested operation.

[ENOTCONN]

Requested operation requires a connection.

This error code indicates one of the following:

• The socket_descriptor is not for a socket that is in a connected state.
• The socket_descriptor has not had SSL support enabled. This usually means that an SSL_Create() has not been completed for this socket_descriptor.

[ENOTSOCK]

The specified descriptor does not reference a socket.

[EPIPE]

Broken pipe.

[ETIMEDOUT]

A remote host did not respond within the timeout period.

[EUNATCH]

The protocol required to support the specified address family is not available at this time.

[EUNKNOWN]

Unknown system state.

[EWOULDBLOCK]

Operation would have caused the thread to be suspended.

Error Messages

Usage Notes

1. The SSL_Write() function is only valid on sockets that have an address family of AF_INET or AF_INET6 and a socket type of SOCK_STREAM. If the descriptor pointed to by the handle structure parameter does not have the correct address family and socket type, [SSL_ERROR_IO] is returned and the errno value is set to EINVAL.
   
   
2. There is no maximum length of the data that can be written. However, SSL will segment the data into multiple SSL record buffers if it will not fit in one SSL record buffer. The maximum SSL record size is 32 KB minus the necessary SSL record headers.
   
   
3. If the createFlags field in the SSLHandle specifies a value that does not include the SSL_ENCRYPT flag, then this function will simply call the sockets write() function.
   
   
4. Unpredictable results will occur when attempting to mix calls to SSL_Write() and any of the sockets write functions (send(), write(), writev(), and so forth). It is strongly suggested that you do not mix the SSL_Write() API with any of the sockets write functions.

Related Information

• SSL_Create()--Enable SSL Support for the Specified Socket Descriptor
  
  
• SSL_Destroy()--End SSL Support for the Specified SSL Session
  
  
• SSL_Handshake()--Initiate the SSL Handshake Protocol
  
  
• SSL_Init()--Initialize the Current Job for SSL
  
  
• SSL_Read()--Receive Data from an SSL-Enabled Socket Descriptor