PR_TransmitFile
===============

Sends a complete file across a connected socket.


Syntax
------

.. code::

   #include <prio.h>

   PRInt32 PR_TransmitFile(
     PRFileDesc *networkSocket,
     PRFileDesc *sourceFile,
     const void *headers,
     PRInt32 hlen,
     PRTransmitFileFlags flags,
     PRIntervalTime timeout);


Parameters
~~~~~~~~~~

The function has the following parameters:

``networkSocket``
   A pointer to a :ref:`PRFileDesc` object representing the connected
   socket to send data over.
``sourceFile``
   A pointer to a :ref:`PRFileDesc` object representing the file to send.
``headers``
   A pointer to the buffer holding the headers to be sent before sending
   data.
``hlen``
   Length of the ``headers`` buffer in bytes.
``flags``
   One of the following flags:

 - :ref:`PR_TRANSMITFILE_KEEP_OPEN` indicates that the socket will be kept
   open after the data is sent.
 - :ref:`PR_TRANSMITFILE_CLOSE_SOCKET` indicates that the connection should
   be closed immediately after successful transfer of the file.

``timeout``
   Time limit for completion of the transmit operation.


Returns
~~~~~~~

-  A positive number indicates the number of bytes successfully written,
   including both the headers and the file.
-  The value -1 indicates a failure. If an error occurs while sending
   the file, the ``PR_TRANSMITFILE_CLOSE_SOCKET`` flag is ignored. The
   reason for the failure can be obtained by calling :ref:`PR_GetError`.


Description
-----------

The :ref:`PR_TransmitFile` function sends a complete file (``sourceFile``)
across a connected socket (``networkSocket``). If ``headers`` is
non-``NULL``, :ref:`PR_TransmitFile` sends the headers across the socket
before sending the file.

The enumeration ``PRTransmitFileFlags``, used in the ``flags``
parameter, is defined as follows:

.. code::

   typedef enum PRTransmitFileFlags {
     PR_TRANSMITFILE_KEEP_OPEN = 0,
     PR_TRANSMITFILE_CLOSE_SOCKET = 1
   } PRTransmitFileFlags;