62 lines
2.2 KiB
Markdown
62 lines
2.2 KiB
Markdown
# 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.
|