70 lines
2.3 KiB
ReStructuredText
70 lines
2.3 KiB
ReStructuredText
PR_ImportTCPSocket
|
|
==================
|
|
|
|
Imports a native TCP socket into NSPR.
|
|
|
|
|
|
Syntax
|
|
------
|
|
|
|
.. code::
|
|
|
|
#include "private/pprio.h"
|
|
|
|
PRFileDesc* PR_ImportTCPSocket(PROsfd osfd);
|
|
|
|
|
|
Parameters
|
|
~~~~~~~~~~
|
|
|
|
The function has the following parameters:
|
|
|
|
``osfd``
|
|
The native file descriptor for the TCP socket to import. On POSIX
|
|
systems, this is an ``int``. On Windows, this is a ``SOCKET``.
|
|
|
|
|
|
Returns
|
|
~~~~~~~
|
|
|
|
The function returns one of the following values:
|
|
|
|
- Upon successful completion, a pointer to the :ref:`PRFileDesc` object
|
|
created for the newly imported native TCP socket.
|
|
- If the import of the native TCP socket failed, ``NULL``.
|
|
|
|
|
|
Description
|
|
-----------
|
|
|
|
A native TCP socket ``osfd`` can be imported into NSPR with
|
|
:ref:`PR_ImportTCPSocket`. The caller gives up control of the native TCP
|
|
socket ``osfd`` and should use the ``PRFileDesc*`` returned by
|
|
:ref:`PR_ImportTCPSocket` instead.
|
|
|
|
Although :ref:`PR_ImportTCPSocket` is a supported function, it is declared
|
|
in ``"private/pprio.h"`` to stress the fact that this function depends
|
|
on the internals of the NSPR implementation. The caller needs to
|
|
understand what NSPR will do to the native file descriptor and make sure
|
|
that NSPR can use the native file descriptor successfully.
|
|
|
|
For example, on POSIX systems, NSPR will put the native file descriptor
|
|
(an ``int``) in non-blocking mode by calling ``fcntl`` to set the
|
|
``O_NONBLOCK`` file status flag on the native file descriptor, and then
|
|
NSPR will call socket functions such as ``recv``, ``send``, and ``poll``
|
|
on the native file descriptor. The caller must not do anything to the
|
|
native file descriptor before the :ref:`PR_ImportTCPSocket` call that will
|
|
prevent the native file descriptor from working in non-blocking mode.
|
|
|
|
Warning
|
|
-------
|
|
|
|
In theory, code that uses :ref:`PR_ImportTCPSocket` may break when NSPR's
|
|
implementation changes. In practice, this is unlikely to happen because
|
|
NSPR's implementation has been stable for years and because of NSPR's
|
|
strong commitment to backward compatibility. Using
|
|
:ref:`PR_ImportTCPSocket` is much more convenient than writing an NSPR I/O
|
|
layer that wraps your native TCP sockets. Of course, it is best if you
|
|
just use :ref:`PR_OpenTCPSocket` or :ref:`PR_NewTCPSocket`. If you are not
|
|
sure whether :ref:`PR_ImportTCPSocket` is right for you, please ask in the
|
|
mozilla.dev.tech.nspr newsgroup.
|