/*
 * zTcpClient.h
 * 
 * The Zen API 
 * Copyright (C) 2008-2009 by LMI Technologies Inc.
 * 
 * Licensed under The MIT License.
 * Redistributions of files must retain the above copyright notice.
 */
#ifndef LMITECH_ZTCPCLIENT_H_INCLUDED
#define LMITECH_ZTCPCLIENT_H_INCLUDED

#include <zSocket.h>
#include <zApiBegin.h>

typedef zHandle   zTcpClient;       // Represents a TCP client.

ZAPI_EXPORT(zStatus) zTcpClient_WaitAny(const zTcpClient* clients, z32u count, zBool* status, z64u timeout); //
//
//  Description:
//      Waits until one or more of the specified TCP clients has bytes to read or until the 
//      specified timeout period elapses. 
//  Arguments:
//      client - An array of clients to wait on. 
//      count - The number of clients in the array.
//      status - An array of returned status values, indicating which clients are ready to be read.
//      timeout - Timeout, in microseconds. 
//  Remarks: 
//      This function will return zERROR_TIMEOUT in the event that none of the clients are ready 
//      for reading by the end of the timeout period. 

ZAPI_EXPORT(zStatus) zTcpClient_Construct(zTcpClient* client); //
//
//  Description:
//      Constructs a zTcpClient object.
//  Arguments:
//      client - Destination for the constructed object handle. 

ZAPI_EXPORT(zStatus) zTcpClient_Destroy(zTcpClient client); //
//
//  Description:
//      Destroys a zTcpClient object. 
//  Arguments:
//      client - The zTcpClient object to be destroyed.
//  Remarks: 
//      If the Client is connected, this function will close the connection before destroying
//      the client object.

ZAPI_EXPORT(zStatus) zTcpClient_SetWriteBuffers(zTcpClient client, zIntPtr socketSize, zIntPtr clientSize); //
//
//  Description:
//      Sets the size of write buffers.
//  Arguments:
//      client - zTcpClient object.
//      socketSize - Size of the write buffer maintained by the underlying socket (-1 to leave unchanged). 
//      clientSize - Size of the write buffer maintained by the client object (-1 to leave unchanged).
//  Remarks: 
//      Socket buffers decouple the sender and receiver, so that the sender does not need to block
//      while waiting for the receiver to receive all bytes. Client buffers improve the efficiency 
//      of the client when performing several small write operations. 
//  Remarks: 
//      By default, the client buffer size is zero and the socket buffer size is determined by the 
//      underlying operating system. If you specify a non-zero client write buffer, remember to 
//      call zTcpClient_Flush to ensure that buffered bytes are written to the underlying zSocket.

ZAPI_EXPORT(zStatus) zTcpClient_SetReadBuffers(zTcpClient client, zIntPtr socketSize, zIntPtr clientSize); //
//
//  Description:
//      Sets the size of read buffers. 
//  Arguments:
//      client - zTcpClient object.
//      socketSize - Size of the read buffer maintained by the underlying socket (-1 to leave unchanged).
//      clientSize - Size of the read buffer maintained by the client object (-1 to leave unchanged).
//  Remarks: 
//      Socket buffers decouple the sender and receiver, so that the sender does not need to block
//      while waiting for the receiver to receive all bytes. Client buffers improve the efficiency 
//      of the client when performing several small read operations. 
//  Remarks: 
//      By default, the client buffer size is zero and the socket buffer size is determined by the 
//      underlying operating system. 

ZAPI_EXPORT(zStatus) zTcpClient_SetWriteTimeout(zTcpClient client, z64u timeout); //
//
//  Description:
//      Sets the timeout duration for write operations.  
//  Arguments:
//      client - zTcpClient object.
//      timeout - Timeout value, in microseconds.
//  Remarks: 
//      By default, zTcpClient objects do not use a timeout interval and may block indefinitely.

ZAPI_EXPORT(zStatus) zTcpClient_SetReadTimeout(zTcpClient client, z64u timeout); //
//
//  Description:
//      Sets the timeout duration for read operations.  
//  Arguments:
//      client - zTcpClient object.
//      timeout - Timeout value, in microseconds.
//  Remarks: 
//      By default, zTcpClient objects do not use a timeout interval and may block indefinitely.

ZAPI_EXPORT(zStatus) zTcpClient_Connect(zTcpClient client, zIPAddress address, z32u port, z64u timeout); //
//
//  Description:
//      Attempts to connect the client to a remote end point until either a connection is established, 
//      the remote end point refuses the connection, or the specified timeout interval elapses. 
//  Arguments:
//      client - zTcpClient object.
//      address - The remote IP address. 
//      port - The remote port number.
//      timeout - The timeout interval, in microseconds.
//  Remarks: 
//      A connection can be established only once per zTcpClient object.  After an initial connection 
//      is created and closed, the zTcpClient object cannot be used to create another connection.

ZAPI_EXPORT(zStatus) zTcpClient_Wait(zTcpClient client, z64u timeout); //
//
//  Description:
//      Waits until the client has bytes to read or until the specified timeout period elapses. 
//  Arguments:
//      client - zTcpClient object.
//      timeout - The timeout interval, in microseconds.
//  Remarks: 
//      This function will return zERROR_TIMEOUT in the event that the client is not ready 
//      for reading by the end of the timeout period. 

ZAPI_EXPORT(zStatus) zTcpClient_Flush(zTcpClient client); //
//
//  Description:
//      Forces any bytes buffered by this zTcpClient object to be written to the underlying zSocket. 
//  Arguments:
//      client - zTcpClient object.
//  Remarks: 
//      This function does not affect underlying socket buffers, and does not guarantee 
//      that all written bytes have been transmitted.

ZAPI_EXPORT(zStatus) zTcpClient_Read(zTcpClient client, void* buffer, zUIntPtr size); //
//
//  Description:
//      Blocks until all requested bytes are read (or until a read timeout occurs),
//      and returns the bytes that were read.
//  Arguments:
//      client - zTcpClient object.
//      buffer - Buffer to receive bytes.
//      size - The number of bytes to return.

ZAPI_EXPORT(zStatus) zTcpClient_Write(zTcpClient client, const void* buffer, zUIntPtr size); //
//
//  Description:
//      Blocks until all of the specified bytes are written (or until a write timeout occurs). 
//  Arguments:
//      client - zTcpClient object.
//      buffer - Buffer of bytes to write. 
//      size - The number of bytes to write.

ZAPI_EXPORT(zSocket) zTcpClient_Socket(zTcpClient client);  //
//
//  Description:
//      Returns the underlying zSocket object.
//  Arguments:
//      client - zTcpClient object.

ZAPI_EXPORT(zUIntPtr) zTcpClient_Available(zTcpClient client);  //
//
//  Description:
//      Returns the number of bytes currently enqueued and available for reading. 
//  Arguments:
//      client - zTcpClient object.
//  Remarks: 
//      This function returns the count of bytes enqueued in the client's internal 
//      read buffer. This does not include any data enqueued in the underlying socket's 
//      read buffer.

ZAPI_EXPORT(zStatus) zTcpClient_LocalEndPoint(zTcpClient client, zIPEndPoint* endPoint); //
//
//  Description:
//      Returns the local end point for a connected client. 
//  Arguments:
//      client - zTcpClient object.
//      endPoint - Local end point.

ZAPI_EXPORT(zStatus) zTcpClient_RemoteEndPoint(zTcpClient client, zIPEndPoint* endPoint); //
//
//  Description:
//      Returns the remote end point for a connected client. 
//  Arguments:
//      client - zTcpClient object.
//      endPoint - Remote end point.

#include <zApiEnd.h>

#endif          /* #ifndef LMITECH_ZTCPCLIENT_H_INCLUDED */
