summaryrefslogtreecommitdiffstats
path: root/docs/nspr/reference/pr_transmitfile.rst
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--docs/nspr/reference/pr_transmitfile.rst76
1 files changed, 76 insertions, 0 deletions
diff --git a/docs/nspr/reference/pr_transmitfile.rst b/docs/nspr/reference/pr_transmitfile.rst
new file mode 100644
index 0000000000..c9812b072e
--- /dev/null
+++ b/docs/nspr/reference/pr_transmitfile.rst
@@ -0,0 +1,76 @@
+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;