pr_importtcpsocket.rst (2369B)
1 PR_ImportTCPSocket 2 ================== 3 4 Imports a native TCP socket into NSPR. 5 6 7 Syntax 8 ------ 9 10 .. code:: 11 12 #include "private/pprio.h" 13 14 PRFileDesc* PR_ImportTCPSocket(PROsfd osfd); 15 16 17 Parameters 18 ~~~~~~~~~~ 19 20 The function has the following parameters: 21 22 ``osfd`` 23 The native file descriptor for the TCP socket to import. On POSIX 24 systems, this is an ``int``. On Windows, this is a ``SOCKET``. 25 26 27 Returns 28 ~~~~~~~ 29 30 The function returns one of the following values: 31 32 - Upon successful completion, a pointer to the :ref:`PRFileDesc` object 33 created for the newly imported native TCP socket. 34 - If the import of the native TCP socket failed, ``NULL``. 35 36 37 Description 38 ----------- 39 40 A native TCP socket ``osfd`` can be imported into NSPR with 41 :ref:`PR_ImportTCPSocket`. The caller gives up control of the native TCP 42 socket ``osfd`` and should use the ``PRFileDesc*`` returned by 43 :ref:`PR_ImportTCPSocket` instead. 44 45 Although :ref:`PR_ImportTCPSocket` is a supported function, it is declared 46 in ``"private/pprio.h"`` to stress the fact that this function depends 47 on the internals of the NSPR implementation. The caller needs to 48 understand what NSPR will do to the native file descriptor and make sure 49 that NSPR can use the native file descriptor successfully. 50 51 For example, on POSIX systems, NSPR will put the native file descriptor 52 (an ``int``) in non-blocking mode by calling ``fcntl`` to set the 53 ``O_NONBLOCK`` file status flag on the native file descriptor, and then 54 NSPR will call socket functions such as ``recv``, ``send``, and ``poll`` 55 on the native file descriptor. The caller must not do anything to the 56 native file descriptor before the :ref:`PR_ImportTCPSocket` call that will 57 prevent the native file descriptor from working in non-blocking mode. 58 59 Warning 60 ------- 61 62 In theory, code that uses :ref:`PR_ImportTCPSocket` may break when NSPR's 63 implementation changes. In practice, this is unlikely to happen because 64 NSPR's implementation has been stable for years and because of NSPR's 65 strong commitment to backward compatibility. Using 66 :ref:`PR_ImportTCPSocket` is much more convenient than writing an NSPR I/O 67 layer that wraps your native TCP sockets. Of course, it is best if you 68 just use :ref:`PR_OpenTCPSocket` or :ref:`PR_NewTCPSocket`. If you are not 69 sure whether :ref:`PR_ImportTCPSocket` is right for you, please ask in the 70 mozilla.dev.tech.nspr newsgroup.