1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/nsprpub/pr/include/prio.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,2022 @@
1.4 +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +/*
1.10 + * File: prio.h
1.11 + *
1.12 + * Description: PR i/o related stuff, such as file system access, file
1.13 + * i/o, socket i/o, etc.
1.14 + */
1.15 +
1.16 +#ifndef prio_h___
1.17 +#define prio_h___
1.18 +
1.19 +#include "prlong.h"
1.20 +#include "prtime.h"
1.21 +#include "prinrval.h"
1.22 +#include "prinet.h"
1.23 +
1.24 +PR_BEGIN_EXTERN_C
1.25 +
1.26 +/* Typedefs */
1.27 +typedef struct PRDir PRDir;
1.28 +typedef struct PRDirEntry PRDirEntry;
1.29 +#ifdef MOZ_UNICODE
1.30 +typedef struct PRDirUTF16 PRDirUTF16;
1.31 +typedef struct PRDirEntryUTF16 PRDirEntryUTF16;
1.32 +#endif /* MOZ_UNICODE */
1.33 +typedef struct PRFileDesc PRFileDesc;
1.34 +typedef struct PRFileInfo PRFileInfo;
1.35 +typedef struct PRFileInfo64 PRFileInfo64;
1.36 +typedef union PRNetAddr PRNetAddr;
1.37 +typedef struct PRIOMethods PRIOMethods;
1.38 +typedef struct PRPollDesc PRPollDesc;
1.39 +typedef struct PRFilePrivate PRFilePrivate;
1.40 +typedef struct PRSendFileData PRSendFileData;
1.41 +
1.42 +/*
1.43 +***************************************************************************
1.44 +** The file descriptor.
1.45 +** This is the primary structure to represent any active open socket,
1.46 +** whether it be a normal file or a network connection. Such objects
1.47 +** are stackable (or layerable). Each layer may have its own set of
1.48 +** method pointers and context private to that layer. All each layer
1.49 +** knows about its neighbors is how to get to their method table.
1.50 +***************************************************************************
1.51 +*/
1.52 +
1.53 +typedef PRIntn PRDescIdentity; /* see: Layering file descriptors */
1.54 +
1.55 +struct PRFileDesc {
1.56 + const PRIOMethods *methods; /* the I/O methods table */
1.57 + PRFilePrivate *secret; /* layer dependent data */
1.58 + PRFileDesc *lower, *higher; /* pointers to adjacent layers */
1.59 + void (PR_CALLBACK *dtor)(PRFileDesc *fd);
1.60 + /* A destructor function for layer */
1.61 + PRDescIdentity identity; /* Identity of this particular layer */
1.62 +};
1.63 +
1.64 +/*
1.65 +***************************************************************************
1.66 +** PRTransmitFileFlags
1.67 +**
1.68 +** Flags for PR_TransmitFile. Pass PR_TRANSMITFILE_CLOSE_SOCKET to
1.69 +** PR_TransmitFile if the connection should be closed after the file
1.70 +** is transmitted.
1.71 +***************************************************************************
1.72 +*/
1.73 +typedef enum PRTransmitFileFlags {
1.74 + PR_TRANSMITFILE_KEEP_OPEN = 0, /* socket is left open after file
1.75 + * is transmitted. */
1.76 + PR_TRANSMITFILE_CLOSE_SOCKET = 1 /* socket is closed after file
1.77 + * is transmitted. */
1.78 +} PRTransmitFileFlags;
1.79 +
1.80 +/*
1.81 +**************************************************************************
1.82 +** Macros for PRNetAddr
1.83 +**
1.84 +** Address families: PR_AF_INET, PR_AF_INET6, PR_AF_LOCAL
1.85 +** IP addresses: PR_INADDR_ANY, PR_INADDR_LOOPBACK, PR_INADDR_BROADCAST
1.86 +**************************************************************************
1.87 +*/
1.88 +
1.89 +#ifdef WIN32
1.90 +
1.91 +#define PR_AF_INET 2
1.92 +#define PR_AF_LOCAL 1
1.93 +#define PR_INADDR_ANY (unsigned long)0x00000000
1.94 +#define PR_INADDR_LOOPBACK 0x7f000001
1.95 +#define PR_INADDR_BROADCAST (unsigned long)0xffffffff
1.96 +
1.97 +#else /* WIN32 */
1.98 +
1.99 +#define PR_AF_INET AF_INET
1.100 +#define PR_AF_LOCAL AF_UNIX
1.101 +#define PR_INADDR_ANY INADDR_ANY
1.102 +#define PR_INADDR_LOOPBACK INADDR_LOOPBACK
1.103 +#define PR_INADDR_BROADCAST INADDR_BROADCAST
1.104 +
1.105 +#endif /* WIN32 */
1.106 +
1.107 +/*
1.108 +** Define PR_AF_INET6 in prcpucfg.h with the same
1.109 +** value as AF_INET6 on platforms with IPv6 support.
1.110 +** Otherwise define it here.
1.111 +*/
1.112 +#ifndef PR_AF_INET6
1.113 +#define PR_AF_INET6 100
1.114 +#endif
1.115 +
1.116 +#define PR_AF_INET_SDP 101
1.117 +#define PR_AF_INET6_SDP 102
1.118 +
1.119 +#ifndef PR_AF_UNSPEC
1.120 +#define PR_AF_UNSPEC 0
1.121 +#endif
1.122 +
1.123 +/*
1.124 +**************************************************************************
1.125 +** A network address
1.126 +**
1.127 +** Only Internet Protocol (IPv4 and IPv6) addresses are supported.
1.128 +** The address family must always represent IPv4 (AF_INET, probably == 2)
1.129 +** or IPv6 (AF_INET6).
1.130 +**************************************************************************
1.131 +*************************************************************************/
1.132 +
1.133 +struct PRIPv6Addr {
1.134 + union {
1.135 + PRUint8 _S6_u8[16];
1.136 + PRUint16 _S6_u16[8];
1.137 + PRUint32 _S6_u32[4];
1.138 + PRUint64 _S6_u64[2];
1.139 + } _S6_un;
1.140 +};
1.141 +#define pr_s6_addr _S6_un._S6_u8
1.142 +#define pr_s6_addr16 _S6_un._S6_u16
1.143 +#define pr_s6_addr32 _S6_un._S6_u32
1.144 +#define pr_s6_addr64 _S6_un._S6_u64
1.145 +
1.146 +typedef struct PRIPv6Addr PRIPv6Addr;
1.147 +
1.148 +union PRNetAddr {
1.149 + struct {
1.150 + PRUint16 family; /* address family (0x00ff maskable) */
1.151 +#ifdef XP_BEOS
1.152 + char data[10]; /* Be has a smaller structure */
1.153 +#else
1.154 + char data[14]; /* raw address data */
1.155 +#endif
1.156 + } raw;
1.157 + struct {
1.158 + PRUint16 family; /* address family (AF_INET) */
1.159 + PRUint16 port; /* port number */
1.160 + PRUint32 ip; /* The actual 32 bits of address */
1.161 +#ifdef XP_BEOS
1.162 + char pad[4]; /* Be has a smaller structure */
1.163 +#else
1.164 + char pad[8];
1.165 +#endif
1.166 + } inet;
1.167 + struct {
1.168 + PRUint16 family; /* address family (AF_INET6) */
1.169 + PRUint16 port; /* port number */
1.170 + PRUint32 flowinfo; /* routing information */
1.171 + PRIPv6Addr ip; /* the actual 128 bits of address */
1.172 + PRUint32 scope_id; /* set of interfaces for a scope */
1.173 + } ipv6;
1.174 +#if defined(XP_UNIX) || defined(XP_OS2)
1.175 + struct { /* Unix domain socket address */
1.176 + PRUint16 family; /* address family (AF_UNIX) */
1.177 +#ifdef XP_OS2
1.178 + char path[108]; /* null-terminated pathname */
1.179 + /* bind fails if size is not 108. */
1.180 +#else
1.181 + char path[104]; /* null-terminated pathname */
1.182 +#endif
1.183 + } local;
1.184 +#endif
1.185 +};
1.186 +
1.187 +/*
1.188 +***************************************************************************
1.189 +** PRSockOption
1.190 +**
1.191 +** The file descriptors can have predefined options set after they file
1.192 +** descriptor is created to change their behavior. Only the options in
1.193 +** the following enumeration are supported.
1.194 +***************************************************************************
1.195 +*/
1.196 +typedef enum PRSockOption
1.197 +{
1.198 + PR_SockOpt_Nonblocking, /* nonblocking io */
1.199 + PR_SockOpt_Linger, /* linger on close if data present */
1.200 + PR_SockOpt_Reuseaddr, /* allow local address reuse */
1.201 + PR_SockOpt_Keepalive, /* keep connections alive */
1.202 + PR_SockOpt_RecvBufferSize, /* send buffer size */
1.203 + PR_SockOpt_SendBufferSize, /* receive buffer size */
1.204 +
1.205 + PR_SockOpt_IpTimeToLive, /* time to live */
1.206 + PR_SockOpt_IpTypeOfService, /* type of service and precedence */
1.207 +
1.208 + PR_SockOpt_AddMember, /* add an IP group membership */
1.209 + PR_SockOpt_DropMember, /* drop an IP group membership */
1.210 + PR_SockOpt_McastInterface, /* multicast interface address */
1.211 + PR_SockOpt_McastTimeToLive, /* multicast timetolive */
1.212 + PR_SockOpt_McastLoopback, /* multicast loopback */
1.213 +
1.214 + PR_SockOpt_NoDelay, /* don't delay send to coalesce packets */
1.215 + PR_SockOpt_MaxSegment, /* maximum segment size */
1.216 + PR_SockOpt_Broadcast, /* enable broadcast */
1.217 + PR_SockOpt_Reuseport, /* allow local address & port reuse on
1.218 + * platforms that support it */
1.219 + PR_SockOpt_Last
1.220 +} PRSockOption;
1.221 +
1.222 +typedef struct PRLinger {
1.223 + PRBool polarity; /* Polarity of the option's setting */
1.224 + PRIntervalTime linger; /* Time to linger before closing */
1.225 +} PRLinger;
1.226 +
1.227 +typedef struct PRMcastRequest {
1.228 + PRNetAddr mcaddr; /* IP multicast address of group */
1.229 + PRNetAddr ifaddr; /* local IP address of interface */
1.230 +} PRMcastRequest;
1.231 +
1.232 +typedef struct PRSocketOptionData
1.233 +{
1.234 + PRSockOption option;
1.235 + union
1.236 + {
1.237 + PRUintn ip_ttl; /* IP time to live */
1.238 + PRUintn mcast_ttl; /* IP multicast time to live */
1.239 + PRUintn tos; /* IP type of service and precedence */
1.240 + PRBool non_blocking; /* Non-blocking (network) I/O */
1.241 + PRBool reuse_addr; /* Allow local address reuse */
1.242 + PRBool reuse_port; /* Allow local address & port reuse on
1.243 + * platforms that support it */
1.244 + PRBool keep_alive; /* Keep connections alive */
1.245 + PRBool mcast_loopback; /* IP multicast loopback */
1.246 + PRBool no_delay; /* Don't delay send to coalesce packets */
1.247 + PRBool broadcast; /* Enable broadcast */
1.248 + PRSize max_segment; /* Maximum segment size */
1.249 + PRSize recv_buffer_size; /* Receive buffer size */
1.250 + PRSize send_buffer_size; /* Send buffer size */
1.251 + PRLinger linger; /* Time to linger on close if data present */
1.252 + PRMcastRequest add_member; /* add an IP group membership */
1.253 + PRMcastRequest drop_member; /* Drop an IP group membership */
1.254 + PRNetAddr mcast_if; /* multicast interface address */
1.255 + } value;
1.256 +} PRSocketOptionData;
1.257 +
1.258 +/*
1.259 +***************************************************************************
1.260 +** PRIOVec
1.261 +**
1.262 +** The I/O vector is used by the write vector method to describe the areas
1.263 +** that are affected by the ouput operation.
1.264 +***************************************************************************
1.265 +*/
1.266 +typedef struct PRIOVec {
1.267 + char *iov_base;
1.268 + int iov_len;
1.269 +} PRIOVec;
1.270 +
1.271 +/*
1.272 +***************************************************************************
1.273 +** Discover what type of socket is being described by the file descriptor.
1.274 +***************************************************************************
1.275 +*/
1.276 +typedef enum PRDescType
1.277 +{
1.278 + PR_DESC_FILE = 1,
1.279 + PR_DESC_SOCKET_TCP = 2,
1.280 + PR_DESC_SOCKET_UDP = 3,
1.281 + PR_DESC_LAYERED = 4,
1.282 + PR_DESC_PIPE = 5
1.283 +} PRDescType;
1.284 +
1.285 +typedef enum PRSeekWhence {
1.286 + PR_SEEK_SET = 0,
1.287 + PR_SEEK_CUR = 1,
1.288 + PR_SEEK_END = 2
1.289 +} PRSeekWhence;
1.290 +
1.291 +NSPR_API(PRDescType) PR_GetDescType(PRFileDesc *file);
1.292 +
1.293 +/*
1.294 +***************************************************************************
1.295 +** PRIOMethods
1.296 +**
1.297 +** The I/O methods table provides procedural access to the functions of
1.298 +** the file descriptor. It is the responsibility of a layer implementor
1.299 +** to provide suitable functions at every entry point. If a layer provides
1.300 +** no functionality, it should call the next lower(higher) function of the
1.301 +** same name (e.g., return fd->lower->method->close(fd->lower));
1.302 +**
1.303 +** Not all functions are implemented for all types of files. In cases where
1.304 +** that is true, the function will return a error indication with an error
1.305 +** code of PR_INVALID_METHOD_ERROR.
1.306 +***************************************************************************
1.307 +*/
1.308 +
1.309 +typedef PRStatus (PR_CALLBACK *PRCloseFN)(PRFileDesc *fd);
1.310 +typedef PRInt32 (PR_CALLBACK *PRReadFN)(PRFileDesc *fd, void *buf, PRInt32 amount);
1.311 +typedef PRInt32 (PR_CALLBACK *PRWriteFN)(PRFileDesc *fd, const void *buf, PRInt32 amount);
1.312 +typedef PRInt32 (PR_CALLBACK *PRAvailableFN)(PRFileDesc *fd);
1.313 +typedef PRInt64 (PR_CALLBACK *PRAvailable64FN)(PRFileDesc *fd);
1.314 +typedef PRStatus (PR_CALLBACK *PRFsyncFN)(PRFileDesc *fd);
1.315 +typedef PROffset32 (PR_CALLBACK *PRSeekFN)(PRFileDesc *fd, PROffset32 offset, PRSeekWhence how);
1.316 +typedef PROffset64 (PR_CALLBACK *PRSeek64FN)(PRFileDesc *fd, PROffset64 offset, PRSeekWhence how);
1.317 +typedef PRStatus (PR_CALLBACK *PRFileInfoFN)(PRFileDesc *fd, PRFileInfo *info);
1.318 +typedef PRStatus (PR_CALLBACK *PRFileInfo64FN)(PRFileDesc *fd, PRFileInfo64 *info);
1.319 +typedef PRInt32 (PR_CALLBACK *PRWritevFN)(
1.320 + PRFileDesc *fd, const PRIOVec *iov, PRInt32 iov_size,
1.321 + PRIntervalTime timeout);
1.322 +typedef PRStatus (PR_CALLBACK *PRConnectFN)(
1.323 + PRFileDesc *fd, const PRNetAddr *addr, PRIntervalTime timeout);
1.324 +typedef PRFileDesc* (PR_CALLBACK *PRAcceptFN) (
1.325 + PRFileDesc *fd, PRNetAddr *addr, PRIntervalTime timeout);
1.326 +typedef PRStatus (PR_CALLBACK *PRBindFN)(PRFileDesc *fd, const PRNetAddr *addr);
1.327 +typedef PRStatus (PR_CALLBACK *PRListenFN)(PRFileDesc *fd, PRIntn backlog);
1.328 +typedef PRStatus (PR_CALLBACK *PRShutdownFN)(PRFileDesc *fd, PRIntn how);
1.329 +typedef PRInt32 (PR_CALLBACK *PRRecvFN)(
1.330 + PRFileDesc *fd, void *buf, PRInt32 amount,
1.331 + PRIntn flags, PRIntervalTime timeout);
1.332 +typedef PRInt32 (PR_CALLBACK *PRSendFN) (
1.333 + PRFileDesc *fd, const void *buf, PRInt32 amount,
1.334 + PRIntn flags, PRIntervalTime timeout);
1.335 +typedef PRInt32 (PR_CALLBACK *PRRecvfromFN)(
1.336 + PRFileDesc *fd, void *buf, PRInt32 amount,
1.337 + PRIntn flags, PRNetAddr *addr, PRIntervalTime timeout);
1.338 +typedef PRInt32 (PR_CALLBACK *PRSendtoFN)(
1.339 + PRFileDesc *fd, const void *buf, PRInt32 amount,
1.340 + PRIntn flags, const PRNetAddr *addr, PRIntervalTime timeout);
1.341 +typedef PRInt16 (PR_CALLBACK *PRPollFN)(
1.342 + PRFileDesc *fd, PRInt16 in_flags, PRInt16 *out_flags);
1.343 +typedef PRInt32 (PR_CALLBACK *PRAcceptreadFN)(
1.344 + PRFileDesc *sd, PRFileDesc **nd, PRNetAddr **raddr,
1.345 + void *buf, PRInt32 amount, PRIntervalTime t);
1.346 +typedef PRInt32 (PR_CALLBACK *PRTransmitfileFN)(
1.347 + PRFileDesc *sd, PRFileDesc *fd, const void *headers,
1.348 + PRInt32 hlen, PRTransmitFileFlags flags, PRIntervalTime t);
1.349 +typedef PRStatus (PR_CALLBACK *PRGetsocknameFN)(PRFileDesc *fd, PRNetAddr *addr);
1.350 +typedef PRStatus (PR_CALLBACK *PRGetpeernameFN)(PRFileDesc *fd, PRNetAddr *addr);
1.351 +typedef PRStatus (PR_CALLBACK *PRGetsocketoptionFN)(
1.352 + PRFileDesc *fd, PRSocketOptionData *data);
1.353 +typedef PRStatus (PR_CALLBACK *PRSetsocketoptionFN)(
1.354 + PRFileDesc *fd, const PRSocketOptionData *data);
1.355 +typedef PRInt32 (PR_CALLBACK *PRSendfileFN)(
1.356 + PRFileDesc *networkSocket, PRSendFileData *sendData,
1.357 + PRTransmitFileFlags flags, PRIntervalTime timeout);
1.358 +typedef PRStatus (PR_CALLBACK *PRConnectcontinueFN)(
1.359 + PRFileDesc *fd, PRInt16 out_flags);
1.360 +typedef PRIntn (PR_CALLBACK *PRReservedFN)(PRFileDesc *fd);
1.361 +
1.362 +struct PRIOMethods {
1.363 + PRDescType file_type; /* Type of file represented (tos) */
1.364 + PRCloseFN close; /* close file and destroy descriptor */
1.365 + PRReadFN read; /* read up to specified bytes into buffer */
1.366 + PRWriteFN write; /* write specified bytes from buffer */
1.367 + PRAvailableFN available; /* determine number of bytes available */
1.368 + PRAvailable64FN available64; /* ditto, 64 bit */
1.369 + PRFsyncFN fsync; /* flush all buffers to permanent store */
1.370 + PRSeekFN seek; /* position the file to the desired place */
1.371 + PRSeek64FN seek64; /* ditto, 64 bit */
1.372 + PRFileInfoFN fileInfo; /* Get information about an open file */
1.373 + PRFileInfo64FN fileInfo64; /* ditto, 64 bit */
1.374 + PRWritevFN writev; /* Write segments as described by iovector */
1.375 + PRConnectFN connect; /* Connect to the specified (net) address */
1.376 + PRAcceptFN accept; /* Accept a connection for a (net) peer */
1.377 + PRBindFN bind; /* Associate a (net) address with the fd */
1.378 + PRListenFN listen; /* Prepare to listen for (net) connections */
1.379 + PRShutdownFN shutdown; /* Shutdown a (net) connection */
1.380 + PRRecvFN recv; /* Solicit up the the specified bytes */
1.381 + PRSendFN send; /* Send all the bytes specified */
1.382 + PRRecvfromFN recvfrom; /* Solicit (net) bytes and report source */
1.383 + PRSendtoFN sendto; /* Send bytes to (net) address specified */
1.384 + PRPollFN poll; /* Test the fd to see if it is ready */
1.385 + PRAcceptreadFN acceptread; /* Accept and read on a new (net) fd */
1.386 + PRTransmitfileFN transmitfile; /* Transmit at entire file */
1.387 + PRGetsocknameFN getsockname; /* Get (net) address associated with fd */
1.388 + PRGetpeernameFN getpeername; /* Get peer's (net) address */
1.389 + PRReservedFN reserved_fn_6; /* reserved for future use */
1.390 + PRReservedFN reserved_fn_5; /* reserved for future use */
1.391 + PRGetsocketoptionFN getsocketoption;
1.392 + /* Get current setting of specified option */
1.393 + PRSetsocketoptionFN setsocketoption;
1.394 + /* Set value of specified option */
1.395 + PRSendfileFN sendfile; /* Send a (partial) file with header/trailer*/
1.396 + PRConnectcontinueFN connectcontinue;
1.397 + /* Continue a nonblocking connect */
1.398 + PRReservedFN reserved_fn_3; /* reserved for future use */
1.399 + PRReservedFN reserved_fn_2; /* reserved for future use */
1.400 + PRReservedFN reserved_fn_1; /* reserved for future use */
1.401 + PRReservedFN reserved_fn_0; /* reserved for future use */
1.402 +};
1.403 +
1.404 +/*
1.405 + **************************************************************************
1.406 + * FUNCTION: PR_GetSpecialFD
1.407 + * DESCRIPTION: Get the file descriptor that represents the standard input,
1.408 + * output, or error stream.
1.409 + * INPUTS:
1.410 + * PRSpecialFD id
1.411 + * A value indicating the type of stream desired:
1.412 + * PR_StandardInput: standard input
1.413 + * PR_StandardOuput: standard output
1.414 + * PR_StandardError: standard error
1.415 + * OUTPUTS: none
1.416 + * RETURNS: PRFileDesc *
1.417 + * If the argument is valid, PR_GetSpecialFD returns a file descriptor
1.418 + * that represents the corresponding standard I/O stream. Otherwise,
1.419 + * PR_GetSpecialFD returns NULL and sets error PR_INVALID_ARGUMENT_ERROR.
1.420 + **************************************************************************
1.421 + */
1.422 +
1.423 +typedef enum PRSpecialFD
1.424 +{
1.425 + PR_StandardInput, /* standard input */
1.426 + PR_StandardOutput, /* standard output */
1.427 + PR_StandardError /* standard error */
1.428 +} PRSpecialFD;
1.429 +
1.430 +NSPR_API(PRFileDesc*) PR_GetSpecialFD(PRSpecialFD id);
1.431 +
1.432 +#define PR_STDIN PR_GetSpecialFD(PR_StandardInput)
1.433 +#define PR_STDOUT PR_GetSpecialFD(PR_StandardOutput)
1.434 +#define PR_STDERR PR_GetSpecialFD(PR_StandardError)
1.435 +
1.436 +/*
1.437 + **************************************************************************
1.438 + * Layering file descriptors
1.439 + *
1.440 + * File descriptors may be layered. Each layer has it's own identity.
1.441 + * Identities are allocated by the runtime and are to be associated
1.442 + * (by the layer implementor) with all layers that are of that type.
1.443 + * It is then possible to scan the chain of layers and find a layer
1.444 + * that one recongizes and therefore predict that it will implement
1.445 + * a desired protocol.
1.446 + *
1.447 + * There are three well-known identities:
1.448 + * PR_INVALID_IO_LAYER => an invalid layer identity, for error return
1.449 + * PR_TOP_IO_LAYER => the identity of the top of the stack
1.450 + * PR_NSPR_IO_LAYER => the identity used by NSPR proper
1.451 + * PR_TOP_IO_LAYER may be used as a shorthand for identifying the topmost
1.452 + * layer of an existing stack. Ie., the following two constructs are
1.453 + * equivalent.
1.454 + *
1.455 + * rv = PR_PushIOLayer(stack, PR_TOP_IO_LAYER, my_layer);
1.456 + * rv = PR_PushIOLayer(stack, PR_GetLayersIdentity(stack), my_layer)
1.457 + *
1.458 + * A string may be associated with the creation of the identity. It
1.459 + * will be copied by the runtime. If queried the runtime will return
1.460 + * a reference to that copied string (not yet another copy). There
1.461 + * is no facility for deleting an identity.
1.462 + **************************************************************************
1.463 + */
1.464 +
1.465 +#define PR_IO_LAYER_HEAD (PRDescIdentity)-3
1.466 +#define PR_INVALID_IO_LAYER (PRDescIdentity)-1
1.467 +#define PR_TOP_IO_LAYER (PRDescIdentity)-2
1.468 +#define PR_NSPR_IO_LAYER (PRDescIdentity)0
1.469 +
1.470 +NSPR_API(PRDescIdentity) PR_GetUniqueIdentity(const char *layer_name);
1.471 +NSPR_API(const char*) PR_GetNameForIdentity(PRDescIdentity ident);
1.472 +NSPR_API(PRDescIdentity) PR_GetLayersIdentity(PRFileDesc* fd);
1.473 +NSPR_API(PRFileDesc*) PR_GetIdentitiesLayer(PRFileDesc* fd_stack, PRDescIdentity id);
1.474 +
1.475 +/*
1.476 + **************************************************************************
1.477 + * PR_GetDefaultIOMethods: Accessing the default methods table.
1.478 + * You may get a pointer to the default methods table by calling this function.
1.479 + * You may then select any elements from that table with which to build your
1.480 + * layer's methods table. You may NOT modify the table directly.
1.481 + **************************************************************************
1.482 + */
1.483 +NSPR_API(const PRIOMethods *) PR_GetDefaultIOMethods(void);
1.484 +
1.485 +/*
1.486 + **************************************************************************
1.487 + * Creating a layer
1.488 + *
1.489 + * A new layer may be allocated by calling PR_CreateIOLayerStub(). The
1.490 + * file descriptor returned will contain the pointer to the methods table
1.491 + * provided. The runtime will not modify the table nor test its correctness.
1.492 + **************************************************************************
1.493 + */
1.494 +NSPR_API(PRFileDesc*) PR_CreateIOLayerStub(
1.495 + PRDescIdentity ident, const PRIOMethods *methods);
1.496 +
1.497 +/*
1.498 + **************************************************************************
1.499 + * Creating a layer
1.500 + *
1.501 + * A new stack may be created by calling PR_CreateIOLayer(). The
1.502 + * file descriptor returned will point to the top of the stack, which has
1.503 + * the layer 'fd' as the topmost layer.
1.504 + *
1.505 + * NOTE: This function creates a new style stack, which has a fixed, dummy
1.506 + * header. The old style stack, created by a call to PR_PushIOLayer,
1.507 + * results in modifying contents of the top layer of the stack, when
1.508 + * pushing and popping layers of the stack.
1.509 + **************************************************************************
1.510 + */
1.511 +NSPR_API(PRFileDesc*) PR_CreateIOLayer(PRFileDesc* fd);
1.512 +
1.513 +/*
1.514 + **************************************************************************
1.515 + * Pushing a layer
1.516 + *
1.517 + * A file descriptor (perhaps allocated using PR_CreateIOLayerStub()) may
1.518 + * be pushed into an existing stack of file descriptors at any point the
1.519 + * caller deems appropriate. The new layer will be inserted into the stack
1.520 + * just above the layer with the indicated identity.
1.521 + *
1.522 + * Note: Even if the identity parameter indicates the top-most layer of
1.523 + * the stack, the value of the file descriptor describing the original
1.524 + * stack will not change.
1.525 + **************************************************************************
1.526 + */
1.527 +NSPR_API(PRStatus) PR_PushIOLayer(
1.528 + PRFileDesc *fd_stack, PRDescIdentity id, PRFileDesc *layer);
1.529 +
1.530 +/*
1.531 + **************************************************************************
1.532 + * Popping a layer
1.533 + *
1.534 + * A layer may be popped from a stack by indicating the identity of the
1.535 + * layer to be removed. If found, a pointer to the removed object will
1.536 + * be returned to the caller. The object then becomes the responsibility
1.537 + * of the caller.
1.538 + *
1.539 + * Note: Even if the identity indicates the top layer of the stack, the
1.540 + * reference returned will not be the file descriptor for the stack and
1.541 + * that file descriptor will remain valid.
1.542 + **************************************************************************
1.543 + */
1.544 +NSPR_API(PRFileDesc*) PR_PopIOLayer(PRFileDesc *fd_stack, PRDescIdentity id);
1.545 +
1.546 +/*
1.547 + **************************************************************************
1.548 + * FUNCTION: PR_Open
1.549 + * DESCRIPTION: Open a file for reading, writing, or both.
1.550 + * INPUTS:
1.551 + * const char *name
1.552 + * The path name of the file to be opened
1.553 + * PRIntn flags
1.554 + * The file status flags.
1.555 + * It is a bitwise OR of the following bit flags (only one of
1.556 + * the first three flags below may be used):
1.557 + * PR_RDONLY Open for reading only.
1.558 + * PR_WRONLY Open for writing only.
1.559 + * PR_RDWR Open for reading and writing.
1.560 + * PR_CREATE_FILE If the file does not exist, the file is created
1.561 + * If the file exists, this flag has no effect.
1.562 + * PR_SYNC If set, each write will wait for both the file data
1.563 + * and file status to be physically updated.
1.564 + * PR_APPEND The file pointer is set to the end of
1.565 + * the file prior to each write.
1.566 + * PR_TRUNCATE If the file exists, its length is truncated to 0.
1.567 + * PR_EXCL With PR_CREATE_FILE, if the file does not exist,
1.568 + * the file is created. If the file already
1.569 + * exists, no action and NULL is returned
1.570 + *
1.571 + * PRIntn mode
1.572 + * The access permission bits of the file mode, if the file is
1.573 + * created when PR_CREATE_FILE is on.
1.574 + * OUTPUTS: None
1.575 + * RETURNS: PRFileDesc *
1.576 + * If the file is successfully opened,
1.577 + * returns a pointer to the PRFileDesc
1.578 + * created for the newly opened file.
1.579 + * Returns a NULL pointer if the open
1.580 + * failed.
1.581 + * SIDE EFFECTS:
1.582 + * RESTRICTIONS:
1.583 + * MEMORY:
1.584 + * The return value, if not NULL, points to a dynamically allocated
1.585 + * PRFileDesc object.
1.586 + * ALGORITHM:
1.587 + **************************************************************************
1.588 + */
1.589 +
1.590 +/* Open flags */
1.591 +#define PR_RDONLY 0x01
1.592 +#define PR_WRONLY 0x02
1.593 +#define PR_RDWR 0x04
1.594 +#define PR_CREATE_FILE 0x08
1.595 +#define PR_APPEND 0x10
1.596 +#define PR_TRUNCATE 0x20
1.597 +#define PR_SYNC 0x40
1.598 +#define PR_EXCL 0x80
1.599 +
1.600 +/*
1.601 +** File modes ....
1.602 +**
1.603 +** CAVEAT: 'mode' is currently only applicable on UNIX platforms.
1.604 +** The 'mode' argument may be ignored by PR_Open on other platforms.
1.605 +**
1.606 +** 00400 Read by owner.
1.607 +** 00200 Write by owner.
1.608 +** 00100 Execute (search if a directory) by owner.
1.609 +** 00040 Read by group.
1.610 +** 00020 Write by group.
1.611 +** 00010 Execute by group.
1.612 +** 00004 Read by others.
1.613 +** 00002 Write by others
1.614 +** 00001 Execute by others.
1.615 +**
1.616 +*/
1.617 +
1.618 +NSPR_API(PRFileDesc*) PR_Open(const char *name, PRIntn flags, PRIntn mode);
1.619 +
1.620 +/*
1.621 + **************************************************************************
1.622 + * FUNCTION: PR_OpenFile
1.623 + * DESCRIPTION:
1.624 + * Open a file for reading, writing, or both.
1.625 + * PR_OpenFile has the same prototype as PR_Open but implements
1.626 + * the specified file mode where possible.
1.627 + **************************************************************************
1.628 + */
1.629 +
1.630 +/* File mode bits */
1.631 +#define PR_IRWXU 00700 /* read, write, execute/search by owner */
1.632 +#define PR_IRUSR 00400 /* read permission, owner */
1.633 +#define PR_IWUSR 00200 /* write permission, owner */
1.634 +#define PR_IXUSR 00100 /* execute/search permission, owner */
1.635 +#define PR_IRWXG 00070 /* read, write, execute/search by group */
1.636 +#define PR_IRGRP 00040 /* read permission, group */
1.637 +#define PR_IWGRP 00020 /* write permission, group */
1.638 +#define PR_IXGRP 00010 /* execute/search permission, group */
1.639 +#define PR_IRWXO 00007 /* read, write, execute/search by others */
1.640 +#define PR_IROTH 00004 /* read permission, others */
1.641 +#define PR_IWOTH 00002 /* write permission, others */
1.642 +#define PR_IXOTH 00001 /* execute/search permission, others */
1.643 +
1.644 +NSPR_API(PRFileDesc*) PR_OpenFile(
1.645 + const char *name, PRIntn flags, PRIntn mode);
1.646 +
1.647 +#ifdef MOZ_UNICODE
1.648 +/*
1.649 + * EXPERIMENTAL: This function may be removed in a future release.
1.650 + */
1.651 +NSPR_API(PRFileDesc*) PR_OpenFileUTF16(
1.652 + const PRUnichar *name, PRIntn flags, PRIntn mode);
1.653 +#endif /* MOZ_UNICODE */
1.654 +
1.655 +/*
1.656 + **************************************************************************
1.657 + * FUNCTION: PR_Close
1.658 + * DESCRIPTION:
1.659 + * Close a file or socket.
1.660 + * INPUTS:
1.661 + * PRFileDesc *fd
1.662 + * a pointer to a PRFileDesc.
1.663 + * OUTPUTS:
1.664 + * None.
1.665 + * RETURN:
1.666 + * PRStatus
1.667 + * SIDE EFFECTS:
1.668 + * RESTRICTIONS:
1.669 + * None.
1.670 + * MEMORY:
1.671 + * The dynamic memory pointed to by the argument fd is freed.
1.672 + **************************************************************************
1.673 + */
1.674 +
1.675 +NSPR_API(PRStatus) PR_Close(PRFileDesc *fd);
1.676 +
1.677 +/*
1.678 + **************************************************************************
1.679 + * FUNCTION: PR_Read
1.680 + * DESCRIPTION:
1.681 + * Read bytes from a file or socket.
1.682 + * The operation will block until either an end of stream indication is
1.683 + * encountered, some positive number of bytes are transferred, or there
1.684 + * is an error. No more than 'amount' bytes will be transferred.
1.685 + * INPUTS:
1.686 + * PRFileDesc *fd
1.687 + * pointer to the PRFileDesc object for the file or socket
1.688 + * void *buf
1.689 + * pointer to a buffer to hold the data read in.
1.690 + * PRInt32 amount
1.691 + * the size of 'buf' (in bytes)
1.692 + * OUTPUTS:
1.693 + * RETURN:
1.694 + * PRInt32
1.695 + * a positive number indicates the number of bytes actually read in.
1.696 + * 0 means end of file is reached or the network connection is closed.
1.697 + * -1 indicates a failure. The reason for the failure is obtained
1.698 + * by calling PR_GetError().
1.699 + * SIDE EFFECTS:
1.700 + * data is written into the buffer pointed to by 'buf'.
1.701 + * RESTRICTIONS:
1.702 + * None.
1.703 + * MEMORY:
1.704 + * N/A
1.705 + * ALGORITHM:
1.706 + * N/A
1.707 + **************************************************************************
1.708 + */
1.709 +
1.710 +NSPR_API(PRInt32) PR_Read(PRFileDesc *fd, void *buf, PRInt32 amount);
1.711 +
1.712 +/*
1.713 + ***************************************************************************
1.714 + * FUNCTION: PR_Write
1.715 + * DESCRIPTION:
1.716 + * Write a specified number of bytes to a file or socket. The thread
1.717 + * invoking this function blocks until all the data is written.
1.718 + * INPUTS:
1.719 + * PRFileDesc *fd
1.720 + * pointer to a PRFileDesc object that refers to a file or socket
1.721 + * const void *buf
1.722 + * pointer to the buffer holding the data
1.723 + * PRInt32 amount
1.724 + * amount of data in bytes to be written from the buffer
1.725 + * OUTPUTS:
1.726 + * None.
1.727 + * RETURN: PRInt32
1.728 + * A positive number indicates the number of bytes successfully written.
1.729 + * A -1 is an indication that the operation failed. The reason
1.730 + * for the failure is obtained by calling PR_GetError().
1.731 + ***************************************************************************
1.732 + */
1.733 +
1.734 +NSPR_API(PRInt32) PR_Write(PRFileDesc *fd,const void *buf,PRInt32 amount);
1.735 +
1.736 +/*
1.737 + ***************************************************************************
1.738 + * FUNCTION: PR_Writev
1.739 + * DESCRIPTION:
1.740 + * Write data to a socket. The data is organized in a PRIOVec array. The
1.741 + * operation will block until all the data is written or the operation
1.742 + * fails.
1.743 + * INPUTS:
1.744 + * PRFileDesc *fd
1.745 + * Pointer that points to a PRFileDesc object for a socket.
1.746 + * const PRIOVec *iov
1.747 + * An array of PRIOVec. PRIOVec is a struct with the following
1.748 + * two fields:
1.749 + * char *iov_base;
1.750 + * int iov_len;
1.751 + * PRInt32 iov_size
1.752 + * Number of elements in the iov array. The value of this
1.753 + * argument must not be greater than PR_MAX_IOVECTOR_SIZE.
1.754 + * If it is, the method will fail (PR_BUFFER_OVERFLOW_ERROR).
1.755 + * PRIntervalTime timeout
1.756 + * Time limit for completion of the entire write operation.
1.757 + * OUTPUTS:
1.758 + * None
1.759 + * RETURN:
1.760 + * A positive number indicates the number of bytes successfully written.
1.761 + * A -1 is an indication that the operation failed. The reason
1.762 + * for the failure is obtained by calling PR_GetError().
1.763 + ***************************************************************************
1.764 + */
1.765 +
1.766 +#define PR_MAX_IOVECTOR_SIZE 16 /* 'iov_size' must be <= */
1.767 +
1.768 +NSPR_API(PRInt32) PR_Writev(
1.769 + PRFileDesc *fd, const PRIOVec *iov, PRInt32 iov_size,
1.770 + PRIntervalTime timeout);
1.771 +
1.772 +/*
1.773 + ***************************************************************************
1.774 + * FUNCTION: PR_Delete
1.775 + * DESCRIPTION:
1.776 + * Delete a file from the filesystem. The operation may fail if the
1.777 + * file is open.
1.778 + * INPUTS:
1.779 + * const char *name
1.780 + * Path name of the file to be deleted.
1.781 + * OUTPUTS:
1.782 + * None.
1.783 + * RETURN: PRStatus
1.784 + * The function returns PR_SUCCESS if the file is successfully
1.785 + * deleted, otherwise it returns PR_FAILURE.
1.786 + ***************************************************************************
1.787 + */
1.788 +
1.789 +NSPR_API(PRStatus) PR_Delete(const char *name);
1.790 +
1.791 +/**************************************************************************/
1.792 +
1.793 +typedef enum PRFileType
1.794 +{
1.795 + PR_FILE_FILE = 1,
1.796 + PR_FILE_DIRECTORY = 2,
1.797 + PR_FILE_OTHER = 3
1.798 +} PRFileType;
1.799 +
1.800 +struct PRFileInfo {
1.801 + PRFileType type; /* Type of file */
1.802 + PROffset32 size; /* Size, in bytes, of file's contents */
1.803 + PRTime creationTime; /* Creation time per definition of PRTime */
1.804 + PRTime modifyTime; /* Last modification time per definition of PRTime */
1.805 +};
1.806 +
1.807 +struct PRFileInfo64 {
1.808 + PRFileType type; /* Type of file */
1.809 + PROffset64 size; /* Size, in bytes, of file's contents */
1.810 + PRTime creationTime; /* Creation time per definition of PRTime */
1.811 + PRTime modifyTime; /* Last modification time per definition of PRTime */
1.812 +};
1.813 +
1.814 +/****************************************************************************
1.815 + * FUNCTION: PR_GetFileInfo, PR_GetFileInfo64
1.816 + * DESCRIPTION:
1.817 + * Get the information about the file with the given path name. This is
1.818 + * applicable only to NSFileDesc describing 'file' types (see
1.819 + * INPUTS:
1.820 + * const char *fn
1.821 + * path name of the file
1.822 + * OUTPUTS:
1.823 + * PRFileInfo *info
1.824 + * Information about the given file is written into the file
1.825 + * information object pointer to by 'info'.
1.826 + * RETURN: PRStatus
1.827 + * PR_GetFileInfo returns PR_SUCCESS if file information is successfully
1.828 + * obtained, otherwise it returns PR_FAILURE.
1.829 + ***************************************************************************
1.830 + */
1.831 +
1.832 +NSPR_API(PRStatus) PR_GetFileInfo(const char *fn, PRFileInfo *info);
1.833 +NSPR_API(PRStatus) PR_GetFileInfo64(const char *fn, PRFileInfo64 *info);
1.834 +
1.835 +#ifdef MOZ_UNICODE
1.836 +/*
1.837 + * EXPERIMENTAL: This function may be removed in a future release.
1.838 + */
1.839 +NSPR_API(PRStatus) PR_GetFileInfo64UTF16(const PRUnichar *fn, PRFileInfo64 *info);
1.840 +#endif /* MOZ_UNICODE */
1.841 +
1.842 +/*
1.843 + **************************************************************************
1.844 + * FUNCTION: PR_GetOpenFileInfo, PR_GetOpenFileInfo64
1.845 + * DESCRIPTION:
1.846 + * Get information about an open file referred to by the
1.847 + * given PRFileDesc object.
1.848 + * INPUTS:
1.849 + * const PRFileDesc *fd
1.850 + * A reference to a valid, open file.
1.851 + * OUTPUTS:
1.852 + * Same as PR_GetFileInfo, PR_GetFileInfo64
1.853 + * RETURN: PRStatus
1.854 + * PR_GetFileInfo returns PR_SUCCESS if file information is successfully
1.855 + * obtained, otherwise it returns PR_FAILURE.
1.856 + ***************************************************************************
1.857 + */
1.858 +
1.859 +NSPR_API(PRStatus) PR_GetOpenFileInfo(PRFileDesc *fd, PRFileInfo *info);
1.860 +NSPR_API(PRStatus) PR_GetOpenFileInfo64(PRFileDesc *fd, PRFileInfo64 *info);
1.861 +
1.862 +/*
1.863 + **************************************************************************
1.864 + * FUNCTION: PR_Rename
1.865 + * DESCRIPTION:
1.866 + * Rename a file from the old name 'from' to the new name 'to'.
1.867 + * INPUTS:
1.868 + * const char *from
1.869 + * The old name of the file to be renamed.
1.870 + * const char *to
1.871 + * The new name of the file.
1.872 + * OUTPUTS:
1.873 + * None.
1.874 + * RETURN: PRStatus
1.875 + **************************************************************************
1.876 + */
1.877 +
1.878 +NSPR_API(PRStatus) PR_Rename(const char *from, const char *to);
1.879 +
1.880 +/*
1.881 + *************************************************************************
1.882 + * FUNCTION: PR_Access
1.883 + * DESCRIPTION:
1.884 + * Determine accessibility of a file.
1.885 + * INPUTS:
1.886 + * const char *name
1.887 + * path name of the file
1.888 + * PRAccessHow how
1.889 + * specifies which access permission to check for.
1.890 + * It can be one of the following values:
1.891 + * PR_ACCESS_READ_OK Test for read permission
1.892 + * PR_ACCESS_WRITE_OK Test for write permission
1.893 + * PR_ACCESS_EXISTS Check existence of file
1.894 + * OUTPUTS:
1.895 + * None.
1.896 + * RETURN: PRStatus
1.897 + * PR_SUCCESS is returned if the requested access is permitted.
1.898 + * Otherwise, PR_FAILURE is returned. Additional information
1.899 + * regarding the reason for the failure may be retrieved from
1.900 + * PR_GetError().
1.901 + *************************************************************************
1.902 + */
1.903 +
1.904 +typedef enum PRAccessHow {
1.905 + PR_ACCESS_EXISTS = 1,
1.906 + PR_ACCESS_WRITE_OK = 2,
1.907 + PR_ACCESS_READ_OK = 3
1.908 +} PRAccessHow;
1.909 +
1.910 +NSPR_API(PRStatus) PR_Access(const char *name, PRAccessHow how);
1.911 +
1.912 +/*
1.913 + *************************************************************************
1.914 + * FUNCTION: PR_Seek, PR_Seek64
1.915 + * DESCRIPTION:
1.916 + * Moves read-write file offset
1.917 + * INPUTS:
1.918 + * PRFileDesc *fd
1.919 + * Pointer to a PRFileDesc object.
1.920 + * PROffset32, PROffset64 offset
1.921 + * Specifies a value, in bytes, that is used in conjunction
1.922 + * with the 'whence' parameter to set the file pointer. A
1.923 + * negative value causes seeking in the reverse direction.
1.924 + * PRSeekWhence whence
1.925 + * Specifies how to interpret the 'offset' parameter in setting
1.926 + * the file pointer associated with the 'fd' parameter.
1.927 + * Values for the 'whence' parameter are:
1.928 + * PR_SEEK_SET Sets the file pointer to the value of the
1.929 + * 'offset' parameter
1.930 + * PR_SEEK_CUR Sets the file pointer to its current location
1.931 + * plus the value of the offset parameter.
1.932 + * PR_SEEK_END Sets the file pointer to the size of the
1.933 + * file plus the value of the offset parameter.
1.934 + * OUTPUTS:
1.935 + * None.
1.936 + * RETURN: PROffset32, PROffset64
1.937 + * Upon successful completion, the resulting pointer location,
1.938 + * measured in bytes from the beginning of the file, is returned.
1.939 + * If the PR_Seek() function fails, the file offset remains
1.940 + * unchanged, and the returned value is -1. The error code can
1.941 + * then be retrieved via PR_GetError().
1.942 + *************************************************************************
1.943 + */
1.944 +
1.945 +NSPR_API(PROffset32) PR_Seek(PRFileDesc *fd, PROffset32 offset, PRSeekWhence whence);
1.946 +NSPR_API(PROffset64) PR_Seek64(PRFileDesc *fd, PROffset64 offset, PRSeekWhence whence);
1.947 +
1.948 +/*
1.949 + ************************************************************************
1.950 + * FUNCTION: PR_Available
1.951 + * DESCRIPTION:
1.952 + * Determine the amount of data in bytes available for reading
1.953 + * in the given file or socket.
1.954 + * INPUTS:
1.955 + * PRFileDesc *fd
1.956 + * Pointer to a PRFileDesc object that refers to a file or
1.957 + * socket.
1.958 + * OUTPUTS:
1.959 + * None
1.960 + * RETURN: PRInt32, PRInt64
1.961 + * Upon successful completion, PR_Available returns the number of
1.962 + * bytes beyond the current read pointer that is available for
1.963 + * reading. Otherwise, it returns a -1 and the reason for the
1.964 + * failure can be retrieved via PR_GetError().
1.965 + ************************************************************************
1.966 + */
1.967 +
1.968 +NSPR_API(PRInt32) PR_Available(PRFileDesc *fd);
1.969 +NSPR_API(PRInt64) PR_Available64(PRFileDesc *fd);
1.970 +
1.971 +/*
1.972 + ************************************************************************
1.973 + * FUNCTION: PR_Sync
1.974 + * DESCRIPTION:
1.975 + * Sync any buffered data for a fd to its backing device (disk).
1.976 + * INPUTS:
1.977 + * PRFileDesc *fd
1.978 + * Pointer to a PRFileDesc object that refers to a file or
1.979 + * socket
1.980 + * OUTPUTS:
1.981 + * None
1.982 + * RETURN: PRStatus
1.983 + * PR_SUCCESS is returned if the requested access is permitted.
1.984 + * Otherwise, PR_FAILURE is returned.
1.985 + ************************************************************************
1.986 + */
1.987 +
1.988 +NSPR_API(PRStatus) PR_Sync(PRFileDesc *fd);
1.989 +
1.990 +/************************************************************************/
1.991 +
1.992 +struct PRDirEntry {
1.993 + const char *name; /* name of entry, relative to directory name */
1.994 +};
1.995 +
1.996 +#ifdef MOZ_UNICODE
1.997 +struct PRDirEntryUTF16 {
1.998 + const PRUnichar *name; /* name of entry in UTF16, relative to
1.999 + * directory name */
1.1000 +};
1.1001 +#endif /* MOZ_UNICODE */
1.1002 +
1.1003 +#if !defined(NO_NSPR_10_SUPPORT)
1.1004 +#define PR_DirName(dirEntry) (dirEntry->name)
1.1005 +#endif
1.1006 +
1.1007 +/*
1.1008 + *************************************************************************
1.1009 + * FUNCTION: PR_OpenDir
1.1010 + * DESCRIPTION:
1.1011 + * Open the directory by the given name
1.1012 + * INPUTS:
1.1013 + * const char *name
1.1014 + * path name of the directory to be opened
1.1015 + * OUTPUTS:
1.1016 + * None
1.1017 + * RETURN: PRDir *
1.1018 + * If the directory is sucessfully opened, a PRDir object is
1.1019 + * dynamically allocated and a pointer to it is returned.
1.1020 + * If the directory cannot be opened, a NULL pointer is returned.
1.1021 + * MEMORY:
1.1022 + * Upon successful completion, the return value points to
1.1023 + * dynamically allocated memory.
1.1024 + *************************************************************************
1.1025 + */
1.1026 +
1.1027 +NSPR_API(PRDir*) PR_OpenDir(const char *name);
1.1028 +
1.1029 +#ifdef MOZ_UNICODE
1.1030 +/*
1.1031 + * EXPERIMENTAL: This function may be removed in a future release.
1.1032 + */
1.1033 +NSPR_API(PRDirUTF16*) PR_OpenDirUTF16(const PRUnichar *name);
1.1034 +#endif /* MOZ_UNICODE */
1.1035 +
1.1036 +/*
1.1037 + *************************************************************************
1.1038 + * FUNCTION: PR_ReadDir
1.1039 + * DESCRIPTION:
1.1040 + * INPUTS:
1.1041 + * PRDir *dir
1.1042 + * pointer to a PRDir object that designates an open directory
1.1043 + * PRDirFlags flags
1.1044 + * PR_SKIP_NONE Do not skip any files
1.1045 + * PR_SKIP_DOT Skip the directory entry "." that
1.1046 + * represents the current directory
1.1047 + * PR_SKIP_DOT_DOT Skip the directory entry ".." that
1.1048 + * represents the parent directory.
1.1049 + * PR_SKIP_BOTH Skip both '.' and '..'
1.1050 + * PR_SKIP_HIDDEN Skip hidden files
1.1051 + * OUTPUTS:
1.1052 + * RETURN: PRDirEntry*
1.1053 + * Returns a pointer to the next entry in the directory. Returns
1.1054 + * a NULL pointer upon reaching the end of the directory or when an
1.1055 + * error occurs. The actual reason can be retrieved via PR_GetError().
1.1056 + *************************************************************************
1.1057 + */
1.1058 +
1.1059 +typedef enum PRDirFlags {
1.1060 + PR_SKIP_NONE = 0x0,
1.1061 + PR_SKIP_DOT = 0x1,
1.1062 + PR_SKIP_DOT_DOT = 0x2,
1.1063 + PR_SKIP_BOTH = 0x3,
1.1064 + PR_SKIP_HIDDEN = 0x4
1.1065 +} PRDirFlags;
1.1066 +
1.1067 +NSPR_API(PRDirEntry*) PR_ReadDir(PRDir *dir, PRDirFlags flags);
1.1068 +
1.1069 +#ifdef MOZ_UNICODE
1.1070 +/*
1.1071 + * EXPERIMENTAL: This function may be removed in a future release.
1.1072 + */
1.1073 +NSPR_API(PRDirEntryUTF16*) PR_ReadDirUTF16(PRDirUTF16 *dir, PRDirFlags flags);
1.1074 +#endif /* MOZ_UNICODE */
1.1075 +
1.1076 +/*
1.1077 + *************************************************************************
1.1078 + * FUNCTION: PR_CloseDir
1.1079 + * DESCRIPTION:
1.1080 + * Close the specified directory.
1.1081 + * INPUTS:
1.1082 + * PRDir *dir
1.1083 + * The directory to be closed.
1.1084 + * OUTPUTS:
1.1085 + * None
1.1086 + * RETURN: PRStatus
1.1087 + * If successful, will return a status of PR_SUCCESS. Otherwise
1.1088 + * a value of PR_FAILURE. The reason for the failure may be re-
1.1089 + * trieved using PR_GetError().
1.1090 + *************************************************************************
1.1091 + */
1.1092 +
1.1093 +NSPR_API(PRStatus) PR_CloseDir(PRDir *dir);
1.1094 +
1.1095 +#ifdef MOZ_UNICODE
1.1096 +/*
1.1097 + * EXPERIMENTAL: This function may be removed in a future release.
1.1098 + */
1.1099 +NSPR_API(PRStatus) PR_CloseDirUTF16(PRDirUTF16 *dir);
1.1100 +#endif /* MOZ_UNICODE */
1.1101 +
1.1102 +/*
1.1103 + *************************************************************************
1.1104 + * FUNCTION: PR_MkDir
1.1105 + * DESCRIPTION:
1.1106 + * Create a new directory with the given name and access mode.
1.1107 + * INPUTS:
1.1108 + * const char *name
1.1109 + * The name of the directory to be created. All the path components
1.1110 + * up to but not including the leaf component must already exist.
1.1111 + * PRIntn mode
1.1112 + * See 'mode' definiton in PR_Open().
1.1113 + * OUTPUTS:
1.1114 + * None
1.1115 + * RETURN: PRStatus
1.1116 + * If successful, will return a status of PR_SUCCESS. Otherwise
1.1117 + * a value of PR_FAILURE. The reason for the failure may be re-
1.1118 + * trieved using PR_GetError().
1.1119 + *************************************************************************
1.1120 + */
1.1121 +
1.1122 +NSPR_API(PRStatus) PR_MkDir(const char *name, PRIntn mode);
1.1123 +
1.1124 +/*
1.1125 + *************************************************************************
1.1126 + * FUNCTION: PR_MakeDir
1.1127 + * DESCRIPTION:
1.1128 + * Create a new directory with the given name and access mode.
1.1129 + * PR_MakeDir has the same prototype as PR_MkDir but implements
1.1130 + * the specified access mode where possible.
1.1131 + *************************************************************************
1.1132 + */
1.1133 +
1.1134 +NSPR_API(PRStatus) PR_MakeDir(const char *name, PRIntn mode);
1.1135 +
1.1136 +/*
1.1137 + *************************************************************************
1.1138 + * FUNCTION: PR_RmDir
1.1139 + * DESCRIPTION:
1.1140 + * Remove a directory by the given name.
1.1141 + * INPUTS:
1.1142 + * const char *name
1.1143 + * The name of the directory to be removed. All the path components
1.1144 + * must already exist. Only the leaf component will be removed.
1.1145 + * OUTPUTS:
1.1146 + * None
1.1147 + * RETURN: PRStatus
1.1148 + * If successful, will return a status of PR_SUCCESS. Otherwise
1.1149 + * a value of PR_FAILURE. The reason for the failure may be re-
1.1150 + * trieved using PR_GetError().
1.1151 + **************************************************************************
1.1152 + */
1.1153 +
1.1154 +NSPR_API(PRStatus) PR_RmDir(const char *name);
1.1155 +
1.1156 +/*
1.1157 + *************************************************************************
1.1158 + * FUNCTION: PR_NewUDPSocket
1.1159 + * DESCRIPTION:
1.1160 + * Create a new UDP socket.
1.1161 + * INPUTS:
1.1162 + * None
1.1163 + * OUTPUTS:
1.1164 + * None
1.1165 + * RETURN: PRFileDesc*
1.1166 + * Upon successful completion, PR_NewUDPSocket returns a pointer
1.1167 + * to the PRFileDesc created for the newly opened UDP socket.
1.1168 + * Returns a NULL pointer if the creation of a new UDP socket failed.
1.1169 + *
1.1170 + **************************************************************************
1.1171 + */
1.1172 +
1.1173 +NSPR_API(PRFileDesc*) PR_NewUDPSocket(void);
1.1174 +
1.1175 +/*
1.1176 + *************************************************************************
1.1177 + * FUNCTION: PR_NewTCPSocket
1.1178 + * DESCRIPTION:
1.1179 + * Create a new TCP socket.
1.1180 + * INPUTS:
1.1181 + * None
1.1182 + * OUTPUTS:
1.1183 + * None
1.1184 + * RETURN: PRFileDesc*
1.1185 + * Upon successful completion, PR_NewTCPSocket returns a pointer
1.1186 + * to the PRFileDesc created for the newly opened TCP socket.
1.1187 + * Returns a NULL pointer if the creation of a new TCP socket failed.
1.1188 + *
1.1189 + **************************************************************************
1.1190 + */
1.1191 +
1.1192 +NSPR_API(PRFileDesc*) PR_NewTCPSocket(void);
1.1193 +
1.1194 +/*
1.1195 + *************************************************************************
1.1196 + * FUNCTION: PR_OpenUDPSocket
1.1197 + * DESCRIPTION:
1.1198 + * Create a new UDP socket of the specified address family.
1.1199 + * INPUTS:
1.1200 + * PRIntn af
1.1201 + * Address family
1.1202 + * OUTPUTS:
1.1203 + * None
1.1204 + * RETURN: PRFileDesc*
1.1205 + * Upon successful completion, PR_OpenUDPSocket returns a pointer
1.1206 + * to the PRFileDesc created for the newly opened UDP socket.
1.1207 + * Returns a NULL pointer if the creation of a new UDP socket failed.
1.1208 + *
1.1209 + **************************************************************************
1.1210 + */
1.1211 +
1.1212 +NSPR_API(PRFileDesc*) PR_OpenUDPSocket(PRIntn af);
1.1213 +
1.1214 +/*
1.1215 + *************************************************************************
1.1216 + * FUNCTION: PR_OpenTCPSocket
1.1217 + * DESCRIPTION:
1.1218 + * Create a new TCP socket of the specified address family.
1.1219 + * INPUTS:
1.1220 + * PRIntn af
1.1221 + * Address family
1.1222 + * OUTPUTS:
1.1223 + * None
1.1224 + * RETURN: PRFileDesc*
1.1225 + * Upon successful completion, PR_NewTCPSocket returns a pointer
1.1226 + * to the PRFileDesc created for the newly opened TCP socket.
1.1227 + * Returns a NULL pointer if the creation of a new TCP socket failed.
1.1228 + *
1.1229 + **************************************************************************
1.1230 + */
1.1231 +
1.1232 +NSPR_API(PRFileDesc*) PR_OpenTCPSocket(PRIntn af);
1.1233 +
1.1234 +/*
1.1235 + *************************************************************************
1.1236 + * FUNCTION: PR_Connect
1.1237 + * DESCRIPTION:
1.1238 + * Initiate a connection on a socket.
1.1239 + * INPUTS:
1.1240 + * PRFileDesc *fd
1.1241 + * Points to a PRFileDesc object representing a socket
1.1242 + * PRNetAddr *addr
1.1243 + * Specifies the address of the socket in its own communication
1.1244 + * space.
1.1245 + * PRIntervalTime timeout
1.1246 + * The function uses the lesser of the provided timeout and
1.1247 + * the OS's connect timeout. In particular, if you specify
1.1248 + * PR_INTERVAL_NO_TIMEOUT as the timeout, the OS's connection
1.1249 + * time limit will be used.
1.1250 + *
1.1251 + * OUTPUTS:
1.1252 + * None
1.1253 + * RETURN: PRStatus
1.1254 + * Upon successful completion of connection initiation, PR_Connect
1.1255 + * returns PR_SUCCESS. Otherwise, it returns PR_FAILURE. Further
1.1256 + * failure information can be obtained by calling PR_GetError().
1.1257 + **************************************************************************
1.1258 + */
1.1259 +
1.1260 +NSPR_API(PRStatus) PR_Connect(
1.1261 + PRFileDesc *fd, const PRNetAddr *addr, PRIntervalTime timeout);
1.1262 +
1.1263 +/*
1.1264 + *************************************************************************
1.1265 + * FUNCTION: PR_ConnectContinue
1.1266 + * DESCRIPTION:
1.1267 + * Continue a nonblocking connect. After a nonblocking connect
1.1268 + * is initiated with PR_Connect() (which fails with
1.1269 + * PR_IN_PROGRESS_ERROR), one should call PR_Poll() on the socket,
1.1270 + * with the in_flags PR_POLL_WRITE | PR_POLL_EXCEPT. When
1.1271 + * PR_Poll() returns, one calls PR_ConnectContinue() on the
1.1272 + * socket to determine whether the nonblocking connect has
1.1273 + * completed or is still in progress. Repeat the PR_Poll(),
1.1274 + * PR_ConnectContinue() sequence until the nonblocking connect
1.1275 + * has completed.
1.1276 + * INPUTS:
1.1277 + * PRFileDesc *fd
1.1278 + * the file descriptor representing a socket
1.1279 + * PRInt16 out_flags
1.1280 + * the out_flags field of the poll descriptor returned by
1.1281 + * PR_Poll()
1.1282 + * RETURN: PRStatus
1.1283 + * If the nonblocking connect has successfully completed,
1.1284 + * PR_ConnectContinue returns PR_SUCCESS. If PR_ConnectContinue()
1.1285 + * returns PR_FAILURE, call PR_GetError():
1.1286 + * - PR_IN_PROGRESS_ERROR: the nonblocking connect is still in
1.1287 + * progress and has not completed yet. The caller should poll
1.1288 + * on the file descriptor for the in_flags
1.1289 + * PR_POLL_WRITE|PR_POLL_EXCEPT and retry PR_ConnectContinue
1.1290 + * later when PR_Poll() returns.
1.1291 + * - Other errors: the nonblocking connect has failed with this
1.1292 + * error code.
1.1293 + */
1.1294 +
1.1295 +NSPR_API(PRStatus) PR_ConnectContinue(PRFileDesc *fd, PRInt16 out_flags);
1.1296 +
1.1297 +/*
1.1298 + *************************************************************************
1.1299 + * THIS FUNCTION IS DEPRECATED. USE PR_ConnectContinue INSTEAD.
1.1300 + *
1.1301 + * FUNCTION: PR_GetConnectStatus
1.1302 + * DESCRIPTION:
1.1303 + * Get the completion status of a nonblocking connect. After
1.1304 + * a nonblocking connect is initiated with PR_Connect() (which
1.1305 + * fails with PR_IN_PROGRESS_ERROR), one should call PR_Poll()
1.1306 + * on the socket, with the in_flags PR_POLL_WRITE | PR_POLL_EXCEPT.
1.1307 + * When PR_Poll() returns, one calls PR_GetConnectStatus on the
1.1308 + * PRPollDesc structure to determine whether the nonblocking
1.1309 + * connect has succeeded or failed.
1.1310 + * INPUTS:
1.1311 + * const PRPollDesc *pd
1.1312 + * Pointer to a PRPollDesc whose fd member is the socket,
1.1313 + * and in_flags must contain PR_POLL_WRITE and PR_POLL_EXCEPT.
1.1314 + * PR_Poll() should have been called and set the out_flags.
1.1315 + * RETURN: PRStatus
1.1316 + * If the nonblocking connect has successfully completed,
1.1317 + * PR_GetConnectStatus returns PR_SUCCESS. If PR_GetConnectStatus()
1.1318 + * returns PR_FAILURE, call PR_GetError():
1.1319 + * - PR_IN_PROGRESS_ERROR: the nonblocking connect is still in
1.1320 + * progress and has not completed yet.
1.1321 + * - Other errors: the nonblocking connect has failed with this
1.1322 + * error code.
1.1323 + */
1.1324 +
1.1325 +NSPR_API(PRStatus) PR_GetConnectStatus(const PRPollDesc *pd);
1.1326 +
1.1327 +/*
1.1328 + *************************************************************************
1.1329 + * FUNCTION: PR_Accept
1.1330 + * DESCRIPTION:
1.1331 + * Accept a connection on a socket.
1.1332 + * INPUTS:
1.1333 + * PRFileDesc *fd
1.1334 + * Points to a PRFileDesc object representing the rendezvous socket
1.1335 + * on which the caller is willing to accept new connections.
1.1336 + * PRIntervalTime timeout
1.1337 + * Time limit for completion of the accept operation.
1.1338 + * OUTPUTS:
1.1339 + * PRNetAddr *addr
1.1340 + * Returns the address of the connecting entity in its own
1.1341 + * communication space. It may be NULL.
1.1342 + * RETURN: PRFileDesc*
1.1343 + * Upon successful acceptance of a connection, PR_Accept
1.1344 + * returns a valid file descriptor. Otherwise, it returns NULL.
1.1345 + * Further failure information can be obtained by calling PR_GetError().
1.1346 + **************************************************************************
1.1347 + */
1.1348 +
1.1349 +NSPR_API(PRFileDesc*) PR_Accept(
1.1350 + PRFileDesc *fd, PRNetAddr *addr, PRIntervalTime timeout);
1.1351 +
1.1352 +/*
1.1353 + *************************************************************************
1.1354 + * FUNCTION: PR_Bind
1.1355 + * DESCRIPTION:
1.1356 + * Bind an address to a socket.
1.1357 + * INPUTS:
1.1358 + * PRFileDesc *fd
1.1359 + * Points to a PRFileDesc object representing a socket.
1.1360 + * PRNetAddr *addr
1.1361 + * Specifies the address to which the socket will be bound.
1.1362 + * OUTPUTS:
1.1363 + * None
1.1364 + * RETURN: PRStatus
1.1365 + * Upon successful binding of an address to a socket, PR_Bind
1.1366 + * returns PR_SUCCESS. Otherwise, it returns PR_FAILURE. Further
1.1367 + * failure information can be obtained by calling PR_GetError().
1.1368 + **************************************************************************
1.1369 + */
1.1370 +
1.1371 +NSPR_API(PRStatus) PR_Bind(PRFileDesc *fd, const PRNetAddr *addr);
1.1372 +
1.1373 +/*
1.1374 + *************************************************************************
1.1375 + * FUNCTION: PR_Listen
1.1376 + * DESCRIPTION:
1.1377 + * Listen for connections on a socket.
1.1378 + * INPUTS:
1.1379 + * PRFileDesc *fd
1.1380 + * Points to a PRFileDesc object representing a socket that will be
1.1381 + * used to listen for new connections.
1.1382 + * PRIntn backlog
1.1383 + * Specifies the maximum length of the queue of pending connections.
1.1384 + * OUTPUTS:
1.1385 + * None
1.1386 + * RETURN: PRStatus
1.1387 + * Upon successful completion of listen request, PR_Listen
1.1388 + * returns PR_SUCCESS. Otherwise, it returns PR_FAILURE. Further
1.1389 + * failure information can be obtained by calling PR_GetError().
1.1390 + **************************************************************************
1.1391 + */
1.1392 +
1.1393 +NSPR_API(PRStatus) PR_Listen(PRFileDesc *fd, PRIntn backlog);
1.1394 +
1.1395 +/*
1.1396 + *************************************************************************
1.1397 + * FUNCTION: PR_Shutdown
1.1398 + * DESCRIPTION:
1.1399 + * Shut down part of a full-duplex connection on a socket.
1.1400 + * INPUTS:
1.1401 + * PRFileDesc *fd
1.1402 + * Points to a PRFileDesc object representing a connected socket.
1.1403 + * PRIntn how
1.1404 + * Specifies the kind of disallowed operations on the socket.
1.1405 + * PR_SHUTDOWN_RCV - Further receives will be disallowed
1.1406 + * PR_SHUTDOWN_SEND - Further sends will be disallowed
1.1407 + * PR_SHUTDOWN_BOTH - Further sends and receives will be disallowed
1.1408 + * OUTPUTS:
1.1409 + * None
1.1410 + * RETURN: PRStatus
1.1411 + * Upon successful completion of shutdown request, PR_Shutdown
1.1412 + * returns PR_SUCCESS. Otherwise, it returns PR_FAILURE. Further
1.1413 + * failure information can be obtained by calling PR_GetError().
1.1414 + **************************************************************************
1.1415 + */
1.1416 +
1.1417 +typedef enum PRShutdownHow
1.1418 +{
1.1419 + PR_SHUTDOWN_RCV = 0, /* disallow further receives */
1.1420 + PR_SHUTDOWN_SEND = 1, /* disallow further sends */
1.1421 + PR_SHUTDOWN_BOTH = 2 /* disallow further receives and sends */
1.1422 +} PRShutdownHow;
1.1423 +
1.1424 +NSPR_API(PRStatus) PR_Shutdown(PRFileDesc *fd, PRShutdownHow how);
1.1425 +
1.1426 +/*
1.1427 + *************************************************************************
1.1428 + * FUNCTION: PR_Recv
1.1429 + * DESCRIPTION:
1.1430 + * Receive a specified number of bytes from a connected socket.
1.1431 + * The operation will block until some positive number of bytes are
1.1432 + * transferred, a time out has occurred, or there is an error.
1.1433 + * No more than 'amount' bytes will be transferred.
1.1434 + * INPUTS:
1.1435 + * PRFileDesc *fd
1.1436 + * points to a PRFileDesc object representing a socket.
1.1437 + * void *buf
1.1438 + * pointer to a buffer to hold the data received.
1.1439 + * PRInt32 amount
1.1440 + * the size of 'buf' (in bytes)
1.1441 + * PRIntn flags
1.1442 + * must be zero or PR_MSG_PEEK.
1.1443 + * PRIntervalTime timeout
1.1444 + * Time limit for completion of the receive operation.
1.1445 + * OUTPUTS:
1.1446 + * None
1.1447 + * RETURN: PRInt32
1.1448 + * a positive number indicates the number of bytes actually received.
1.1449 + * 0 means the network connection is closed.
1.1450 + * -1 indicates a failure. The reason for the failure is obtained
1.1451 + * by calling PR_GetError().
1.1452 + **************************************************************************
1.1453 + */
1.1454 +
1.1455 +#define PR_MSG_PEEK 0x2
1.1456 +
1.1457 +NSPR_API(PRInt32) PR_Recv(PRFileDesc *fd, void *buf, PRInt32 amount,
1.1458 + PRIntn flags, PRIntervalTime timeout);
1.1459 +
1.1460 +/*
1.1461 + *************************************************************************
1.1462 + * FUNCTION: PR_Send
1.1463 + * DESCRIPTION:
1.1464 + * Send a specified number of bytes from a connected socket.
1.1465 + * The operation will block until all bytes are
1.1466 + * processed, a time out has occurred, or there is an error.
1.1467 + * INPUTS:
1.1468 + * PRFileDesc *fd
1.1469 + * points to a PRFileDesc object representing a socket.
1.1470 + * void *buf
1.1471 + * pointer to a buffer from where the data is sent.
1.1472 + * PRInt32 amount
1.1473 + * the size of 'buf' (in bytes)
1.1474 + * PRIntn flags
1.1475 + * (OBSOLETE - must always be zero)
1.1476 + * PRIntervalTime timeout
1.1477 + * Time limit for completion of the send operation.
1.1478 + * OUTPUTS:
1.1479 + * None
1.1480 + * RETURN: PRInt32
1.1481 + * A positive number indicates the number of bytes successfully processed.
1.1482 + * This number must always equal 'amount'. A -1 is an indication that the
1.1483 + * operation failed. The reason for the failure is obtained by calling
1.1484 + * PR_GetError().
1.1485 + **************************************************************************
1.1486 + */
1.1487 +
1.1488 +NSPR_API(PRInt32) PR_Send(PRFileDesc *fd, const void *buf, PRInt32 amount,
1.1489 + PRIntn flags, PRIntervalTime timeout);
1.1490 +
1.1491 +/*
1.1492 + *************************************************************************
1.1493 + * FUNCTION: PR_RecvFrom
1.1494 + * DESCRIPTION:
1.1495 + * Receive up to a specified number of bytes from socket which may
1.1496 + * or may not be connected.
1.1497 + * The operation will block until one or more bytes are
1.1498 + * transferred, a time out has occurred, or there is an error.
1.1499 + * No more than 'amount' bytes will be transferred.
1.1500 + * INPUTS:
1.1501 + * PRFileDesc *fd
1.1502 + * points to a PRFileDesc object representing a socket.
1.1503 + * void *buf
1.1504 + * pointer to a buffer to hold the data received.
1.1505 + * PRInt32 amount
1.1506 + * the size of 'buf' (in bytes)
1.1507 + * PRIntn flags
1.1508 + * (OBSOLETE - must always be zero)
1.1509 + * PRNetAddr *addr
1.1510 + * Specifies the address of the sending peer. It may be NULL.
1.1511 + * PRIntervalTime timeout
1.1512 + * Time limit for completion of the receive operation.
1.1513 + * OUTPUTS:
1.1514 + * None
1.1515 + * RETURN: PRInt32
1.1516 + * a positive number indicates the number of bytes actually received.
1.1517 + * 0 means the network connection is closed.
1.1518 + * -1 indicates a failure. The reason for the failure is obtained
1.1519 + * by calling PR_GetError().
1.1520 + **************************************************************************
1.1521 + */
1.1522 +
1.1523 +NSPR_API(PRInt32) PR_RecvFrom(
1.1524 + PRFileDesc *fd, void *buf, PRInt32 amount, PRIntn flags,
1.1525 + PRNetAddr *addr, PRIntervalTime timeout);
1.1526 +
1.1527 +/*
1.1528 + *************************************************************************
1.1529 + * FUNCTION: PR_SendTo
1.1530 + * DESCRIPTION:
1.1531 + * Send a specified number of bytes from an unconnected socket.
1.1532 + * The operation will block until all bytes are
1.1533 + * sent, a time out has occurred, or there is an error.
1.1534 + * INPUTS:
1.1535 + * PRFileDesc *fd
1.1536 + * points to a PRFileDesc object representing an unconnected socket.
1.1537 + * void *buf
1.1538 + * pointer to a buffer from where the data is sent.
1.1539 + * PRInt32 amount
1.1540 + * the size of 'buf' (in bytes)
1.1541 + * PRIntn flags
1.1542 + * (OBSOLETE - must always be zero)
1.1543 + * PRNetAddr *addr
1.1544 + * Specifies the address of the peer.
1.1545 +.* PRIntervalTime timeout
1.1546 + * Time limit for completion of the send operation.
1.1547 + * OUTPUTS:
1.1548 + * None
1.1549 + * RETURN: PRInt32
1.1550 + * A positive number indicates the number of bytes successfully sent.
1.1551 + * -1 indicates a failure. The reason for the failure is obtained
1.1552 + * by calling PR_GetError().
1.1553 + **************************************************************************
1.1554 + */
1.1555 +
1.1556 +NSPR_API(PRInt32) PR_SendTo(
1.1557 + PRFileDesc *fd, const void *buf, PRInt32 amount, PRIntn flags,
1.1558 + const PRNetAddr *addr, PRIntervalTime timeout);
1.1559 +
1.1560 +/*
1.1561 +*************************************************************************
1.1562 +** FUNCTION: PR_TransmitFile
1.1563 +** DESCRIPTION:
1.1564 +** Transmitfile sends a complete file (sourceFile) across a socket
1.1565 +** (networkSocket). If headers is non-NULL, the headers will be sent across
1.1566 +** the socket prior to sending the file.
1.1567 +**
1.1568 +** Optionally, the PR_TRANSMITFILE_CLOSE_SOCKET flag may be passed to
1.1569 +** transmitfile. This flag specifies that transmitfile should close the
1.1570 +** socket after sending the data.
1.1571 +**
1.1572 +** INPUTS:
1.1573 +** PRFileDesc *networkSocket
1.1574 +** The socket to send data over
1.1575 +** PRFileDesc *sourceFile
1.1576 +** The file to send
1.1577 +** const void *headers
1.1578 +** A pointer to headers to be sent before sending data
1.1579 +** PRInt32 hlen
1.1580 +** length of header buffers in bytes.
1.1581 +** PRTransmitFileFlags flags
1.1582 +** If the flags indicate that the connection should be closed,
1.1583 +** it will be done immediately after transferring the file, unless
1.1584 +** the operation is unsuccessful.
1.1585 +.* PRIntervalTime timeout
1.1586 + * Time limit for completion of the transmit operation.
1.1587 +**
1.1588 +** RETURNS:
1.1589 +** Returns the number of bytes written or -1 if the operation failed.
1.1590 +** If an error occurs while sending the file, the PR_TRANSMITFILE_CLOSE_
1.1591 +** SOCKET flag is ignored. The reason for the failure is obtained
1.1592 +** by calling PR_GetError().
1.1593 +**************************************************************************
1.1594 +*/
1.1595 +
1.1596 +NSPR_API(PRInt32) PR_TransmitFile(
1.1597 + PRFileDesc *networkSocket, PRFileDesc *sourceFile,
1.1598 + const void *headers, PRInt32 hlen, PRTransmitFileFlags flags,
1.1599 + PRIntervalTime timeout);
1.1600 +
1.1601 +/*
1.1602 +*************************************************************************
1.1603 +** FUNCTION: PR_SendFile
1.1604 +** DESCRIPTION:
1.1605 +** PR_SendFile sends data from a file (sendData->fd) across a socket
1.1606 +** (networkSocket). If specified, a header and/or trailer buffer are sent
1.1607 +** before and after the file, respectively. The file offset, number of bytes
1.1608 +** of file data to send, the header and trailer buffers are specified in the
1.1609 +** sendData argument.
1.1610 +**
1.1611 +** Optionally, if the PR_TRANSMITFILE_CLOSE_SOCKET flag is passed, the
1.1612 +** socket is closed after successfully sending the data.
1.1613 +**
1.1614 +** INPUTS:
1.1615 +** PRFileDesc *networkSocket
1.1616 +** The socket to send data over
1.1617 +** PRSendFileData *sendData
1.1618 +** Contains the FD, file offset and length, header and trailer
1.1619 +** buffer specifications.
1.1620 +** PRTransmitFileFlags flags
1.1621 +** If the flags indicate that the connection should be closed,
1.1622 +** it will be done immediately after transferring the file, unless
1.1623 +** the operation is unsuccessful.
1.1624 +.* PRIntervalTime timeout
1.1625 + * Time limit for completion of the send operation.
1.1626 +**
1.1627 +** RETURNS:
1.1628 +** Returns the number of bytes written or -1 if the operation failed.
1.1629 +** If an error occurs while sending the file, the PR_TRANSMITFILE_CLOSE_
1.1630 +** SOCKET flag is ignored. The reason for the failure is obtained
1.1631 +** by calling PR_GetError().
1.1632 +**************************************************************************
1.1633 +*/
1.1634 +
1.1635 +struct PRSendFileData {
1.1636 + PRFileDesc *fd; /* file to send */
1.1637 + PRUint32 file_offset; /* file offset */
1.1638 + PRSize file_nbytes; /* number of bytes of file data to send */
1.1639 + /* if 0, send data from file_offset to */
1.1640 + /* end-of-file. */
1.1641 + const void *header; /* header buffer */
1.1642 + PRInt32 hlen; /* header len */
1.1643 + const void *trailer; /* trailer buffer */
1.1644 + PRInt32 tlen; /* trailer len */
1.1645 +};
1.1646 +
1.1647 +
1.1648 +NSPR_API(PRInt32) PR_SendFile(
1.1649 + PRFileDesc *networkSocket, PRSendFileData *sendData,
1.1650 + PRTransmitFileFlags flags, PRIntervalTime timeout);
1.1651 +
1.1652 +/*
1.1653 +*************************************************************************
1.1654 +** FUNCTION: PR_AcceptRead
1.1655 +** DESCRIPTION:
1.1656 +** AcceptRead accepts a new connection, returns the newly created
1.1657 +** socket's descriptor and also returns the connecting peer's address.
1.1658 +** AcceptRead, as its name suggests, also receives the first block of data
1.1659 +** sent by the peer.
1.1660 +**
1.1661 +** INPUTS:
1.1662 +** PRFileDesc *listenSock
1.1663 +** A socket descriptor that has been called with the PR_Listen()
1.1664 +** function, also known as the rendezvous socket.
1.1665 +** void *buf
1.1666 +** A pointer to a buffer to receive data sent by the client. This
1.1667 +** buffer must be large enough to receive <amount> bytes of data
1.1668 +** and two PRNetAddr structures, plus an extra 32 bytes. See:
1.1669 +** PR_ACCEPT_READ_BUF_OVERHEAD.
1.1670 +** PRInt32 amount
1.1671 +** The number of bytes of client data to receive. Does not include
1.1672 +** the size of the PRNetAddr structures. If 0, no data will be read
1.1673 +** from the client.
1.1674 +** PRIntervalTime timeout
1.1675 +** The timeout interval only applies to the read portion of the
1.1676 +** operation. PR_AcceptRead will block indefinitely until the
1.1677 +** connection is accepted; the read will timeout after the timeout
1.1678 +** interval elapses.
1.1679 +** OUTPUTS:
1.1680 +** PRFileDesc **acceptedSock
1.1681 +** The file descriptor for the newly connected socket. This parameter
1.1682 +** will only be valid if the function return does not indicate failure.
1.1683 +** PRNetAddr **peerAddr,
1.1684 +** The address of the remote socket. This parameter will only be
1.1685 +** valid if the function return does not indicate failure. The
1.1686 +** returned address is not guaranteed to be properly aligned.
1.1687 +**
1.1688 +** RETURNS:
1.1689 +** The number of bytes read from the client or -1 on failure. The reason
1.1690 +** for the failure is obtained by calling PR_GetError().
1.1691 +**************************************************************************
1.1692 +**/
1.1693 +/* define buffer overhead constant. Add this value to the user's
1.1694 +** data length when allocating a buffer to accept data.
1.1695 +** Example:
1.1696 +** #define USER_DATA_SIZE 10
1.1697 +** char buf[USER_DATA_SIZE + PR_ACCEPT_READ_BUF_OVERHEAD];
1.1698 +** bytesRead = PR_AcceptRead( s, fd, &a, &p, USER_DATA_SIZE, ...);
1.1699 +*/
1.1700 +#define PR_ACCEPT_READ_BUF_OVERHEAD (32+(2*sizeof(PRNetAddr)))
1.1701 +
1.1702 +NSPR_API(PRInt32) PR_AcceptRead(
1.1703 + PRFileDesc *listenSock, PRFileDesc **acceptedSock,
1.1704 + PRNetAddr **peerAddr, void *buf, PRInt32 amount, PRIntervalTime timeout);
1.1705 +
1.1706 +/*
1.1707 +*************************************************************************
1.1708 +** FUNCTION: PR_NewTCPSocketPair
1.1709 +** DESCRIPTION:
1.1710 +** Create a new TCP socket pair. The returned descriptors can be used
1.1711 +** interchangeably; they are interconnected full-duplex descriptors: data
1.1712 +** written to one can be read from the other and vice-versa.
1.1713 +**
1.1714 +** INPUTS:
1.1715 +** None
1.1716 +** OUTPUTS:
1.1717 +** PRFileDesc *fds[2]
1.1718 +** The file descriptor pair for the newly created TCP sockets.
1.1719 +** RETURN: PRStatus
1.1720 +** Upon successful completion of TCP socket pair, PR_NewTCPSocketPair
1.1721 +** returns PR_SUCCESS. Otherwise, it returns PR_FAILURE. Further
1.1722 +** failure information can be obtained by calling PR_GetError().
1.1723 +** XXX can we implement this on windoze and mac?
1.1724 +**************************************************************************
1.1725 +**/
1.1726 +NSPR_API(PRStatus) PR_NewTCPSocketPair(PRFileDesc *fds[2]);
1.1727 +
1.1728 +/*
1.1729 +*************************************************************************
1.1730 +** FUNCTION: PR_GetSockName
1.1731 +** DESCRIPTION:
1.1732 +** Get socket name. Return the network address for this socket.
1.1733 +**
1.1734 +** INPUTS:
1.1735 +** PRFileDesc *fd
1.1736 +** Points to a PRFileDesc object representing the socket.
1.1737 +** OUTPUTS:
1.1738 +** PRNetAddr *addr
1.1739 +** Returns the address of the socket in its own communication space.
1.1740 +** RETURN: PRStatus
1.1741 +** Upon successful completion, PR_GetSockName returns PR_SUCCESS.
1.1742 +** Otherwise, it returns PR_FAILURE. Further failure information can
1.1743 +** be obtained by calling PR_GetError().
1.1744 +**************************************************************************
1.1745 +**/
1.1746 +NSPR_API(PRStatus) PR_GetSockName(PRFileDesc *fd, PRNetAddr *addr);
1.1747 +
1.1748 +/*
1.1749 +*************************************************************************
1.1750 +** FUNCTION: PR_GetPeerName
1.1751 +** DESCRIPTION:
1.1752 +** Get name of the connected peer. Return the network address for the
1.1753 +** connected peer socket.
1.1754 +**
1.1755 +** INPUTS:
1.1756 +** PRFileDesc *fd
1.1757 +** Points to a PRFileDesc object representing the connected peer.
1.1758 +** OUTPUTS:
1.1759 +** PRNetAddr *addr
1.1760 +** Returns the address of the connected peer in its own communication
1.1761 +** space.
1.1762 +** RETURN: PRStatus
1.1763 +** Upon successful completion, PR_GetPeerName returns PR_SUCCESS.
1.1764 +** Otherwise, it returns PR_FAILURE. Further failure information can
1.1765 +** be obtained by calling PR_GetError().
1.1766 +**************************************************************************
1.1767 +**/
1.1768 +NSPR_API(PRStatus) PR_GetPeerName(PRFileDesc *fd, PRNetAddr *addr);
1.1769 +
1.1770 +NSPR_API(PRStatus) PR_GetSocketOption(
1.1771 + PRFileDesc *fd, PRSocketOptionData *data);
1.1772 +
1.1773 +NSPR_API(PRStatus) PR_SetSocketOption(
1.1774 + PRFileDesc *fd, const PRSocketOptionData *data);
1.1775 +
1.1776 +/*
1.1777 + *********************************************************************
1.1778 + *
1.1779 + * File descriptor inheritance
1.1780 + *
1.1781 + *********************************************************************
1.1782 + */
1.1783 +
1.1784 +/*
1.1785 + ************************************************************************
1.1786 + * FUNCTION: PR_SetFDInheritable
1.1787 + * DESCRIPTION:
1.1788 + * Set the inheritance attribute of a file descriptor.
1.1789 + *
1.1790 + * INPUTS:
1.1791 + * PRFileDesc *fd
1.1792 + * Points to a PRFileDesc object.
1.1793 + * PRBool inheritable
1.1794 + * If PR_TRUE, the file descriptor fd is set to be inheritable
1.1795 + * by a child process. If PR_FALSE, the file descriptor is set
1.1796 + * to be not inheritable by a child process.
1.1797 + * RETURN: PRStatus
1.1798 + * Upon successful completion, PR_SetFDInheritable returns PR_SUCCESS.
1.1799 + * Otherwise, it returns PR_FAILURE. Further failure information can
1.1800 + * be obtained by calling PR_GetError().
1.1801 + *************************************************************************
1.1802 + */
1.1803 +NSPR_API(PRStatus) PR_SetFDInheritable(
1.1804 + PRFileDesc *fd,
1.1805 + PRBool inheritable);
1.1806 +
1.1807 +/*
1.1808 + ************************************************************************
1.1809 + * FUNCTION: PR_GetInheritedFD
1.1810 + * DESCRIPTION:
1.1811 + * Get an inherited file descriptor with the specified name.
1.1812 + *
1.1813 + * INPUTS:
1.1814 + * const char *name
1.1815 + * The name of the inherited file descriptor.
1.1816 + * RETURN: PRFileDesc *
1.1817 + * Upon successful completion, PR_GetInheritedFD returns the
1.1818 + * inherited file descriptor with the specified name. Otherwise,
1.1819 + * it returns NULL. Further failure information can be obtained
1.1820 + * by calling PR_GetError().
1.1821 + *************************************************************************
1.1822 + */
1.1823 +NSPR_API(PRFileDesc *) PR_GetInheritedFD(const char *name);
1.1824 +
1.1825 +/*
1.1826 + *********************************************************************
1.1827 + *
1.1828 + * Memory-mapped files
1.1829 + *
1.1830 + *********************************************************************
1.1831 + */
1.1832 +
1.1833 +typedef struct PRFileMap PRFileMap;
1.1834 +
1.1835 +/*
1.1836 + * protection options for read and write accesses of a file mapping
1.1837 + */
1.1838 +typedef enum PRFileMapProtect {
1.1839 + PR_PROT_READONLY, /* read only */
1.1840 + PR_PROT_READWRITE, /* readable, and write is shared */
1.1841 + PR_PROT_WRITECOPY /* readable, and write is private (copy-on-write) */
1.1842 +} PRFileMapProtect;
1.1843 +
1.1844 +NSPR_API(PRFileMap *) PR_CreateFileMap(
1.1845 + PRFileDesc *fd,
1.1846 + PRInt64 size,
1.1847 + PRFileMapProtect prot);
1.1848 +
1.1849 +/*
1.1850 + * return the alignment (in bytes) of the offset argument to PR_MemMap
1.1851 + */
1.1852 +NSPR_API(PRInt32) PR_GetMemMapAlignment(void);
1.1853 +
1.1854 +NSPR_API(void *) PR_MemMap(
1.1855 + PRFileMap *fmap,
1.1856 + PROffset64 offset, /* must be aligned and sized according to the
1.1857 + * return value of PR_GetMemMapAlignment() */
1.1858 + PRUint32 len);
1.1859 +
1.1860 +NSPR_API(PRStatus) PR_MemUnmap(void *addr, PRUint32 len);
1.1861 +
1.1862 +NSPR_API(PRStatus) PR_CloseFileMap(PRFileMap *fmap);
1.1863 +
1.1864 +/*
1.1865 + * Synchronously flush the given memory-mapped address range of the given open
1.1866 + * file to disk. The function does not return until all modified data have
1.1867 + * been written to disk.
1.1868 + *
1.1869 + * On some platforms, the function will call PR_Sync(fd) internally if it is
1.1870 + * necessary for flushing modified data to disk synchronously.
1.1871 + */
1.1872 +NSPR_API(PRStatus) PR_SyncMemMap(
1.1873 + PRFileDesc *fd,
1.1874 + void *addr,
1.1875 + PRUint32 len);
1.1876 +
1.1877 +/*
1.1878 + ******************************************************************
1.1879 + *
1.1880 + * Interprocess communication
1.1881 + *
1.1882 + ******************************************************************
1.1883 + */
1.1884 +
1.1885 +/*
1.1886 + * Creates an anonymous pipe and returns file descriptors for the
1.1887 + * read and write ends of the pipe.
1.1888 + */
1.1889 +
1.1890 +NSPR_API(PRStatus) PR_CreatePipe(
1.1891 + PRFileDesc **readPipe,
1.1892 + PRFileDesc **writePipe
1.1893 +);
1.1894 +
1.1895 +/************************************************************************/
1.1896 +/************** The following definitions are for poll ******************/
1.1897 +/************************************************************************/
1.1898 +
1.1899 +struct PRPollDesc {
1.1900 + PRFileDesc* fd;
1.1901 + PRInt16 in_flags;
1.1902 + PRInt16 out_flags;
1.1903 +};
1.1904 +
1.1905 +/*
1.1906 +** Bit values for PRPollDesc.in_flags or PRPollDesc.out_flags. Binary-or
1.1907 +** these together to produce the desired poll request.
1.1908 +*/
1.1909 +
1.1910 +#if defined(_PR_POLL_BACKCOMPAT)
1.1911 +
1.1912 +#include <poll.h>
1.1913 +#define PR_POLL_READ POLLIN
1.1914 +#define PR_POLL_WRITE POLLOUT
1.1915 +#define PR_POLL_EXCEPT POLLPRI
1.1916 +#define PR_POLL_ERR POLLERR /* only in out_flags */
1.1917 +#define PR_POLL_NVAL POLLNVAL /* only in out_flags when fd is bad */
1.1918 +#define PR_POLL_HUP POLLHUP /* only in out_flags */
1.1919 +
1.1920 +#else /* _PR_POLL_BACKCOMPAT */
1.1921 +
1.1922 +#define PR_POLL_READ 0x1
1.1923 +#define PR_POLL_WRITE 0x2
1.1924 +#define PR_POLL_EXCEPT 0x4
1.1925 +#define PR_POLL_ERR 0x8 /* only in out_flags */
1.1926 +#define PR_POLL_NVAL 0x10 /* only in out_flags when fd is bad */
1.1927 +#define PR_POLL_HUP 0x20 /* only in out_flags */
1.1928 +
1.1929 +#endif /* _PR_POLL_BACKCOMPAT */
1.1930 +
1.1931 +/*
1.1932 +*************************************************************************
1.1933 +** FUNCTION: PR_Poll
1.1934 +** DESCRIPTION:
1.1935 +**
1.1936 +** The call returns as soon as I/O is ready on one or more of the underlying
1.1937 +** socket objects. A count of the number of ready descriptors is
1.1938 +** returned unless a timeout occurs in which case zero is returned.
1.1939 +**
1.1940 +** PRPollDesc.fd should be set to a pointer to a PRFileDesc object
1.1941 +** representing a socket. This field can be set to NULL to indicate to
1.1942 +** PR_Poll that this PRFileDesc object should be ignored.
1.1943 +** PRPollDesc.in_flags should be set to the desired request
1.1944 +** (read/write/except or some combination). Upon successful return from
1.1945 +** this call PRPollDesc.out_flags will be set to indicate what kind of
1.1946 +** i/o can be performed on the respective descriptor. PR_Poll() uses the
1.1947 +** out_flags fields as scratch variables during the call. If PR_Poll()
1.1948 +** returns 0 or -1, the out_flags fields do not contain meaningful values
1.1949 +** and must not be used.
1.1950 +**
1.1951 +** INPUTS:
1.1952 +** PRPollDesc *pds A pointer to an array of PRPollDesc
1.1953 +**
1.1954 +** PRIntn npds The number of elements in the array
1.1955 +** If this argument is zero PR_Poll is
1.1956 +** equivalent to a PR_Sleep(timeout).
1.1957 +**
1.1958 +** PRIntervalTime timeout Amount of time the call will block waiting
1.1959 +** for I/O to become ready. If this time expires
1.1960 +** w/o any I/O becoming ready, the result will
1.1961 +** be zero.
1.1962 +**
1.1963 +** OUTPUTS: None
1.1964 +** RETURN:
1.1965 +** PRInt32 Number of PRPollDesc's with events or zero
1.1966 +** if the function timed out or -1 on failure.
1.1967 +** The reason for the failure is obtained by
1.1968 +** calling PR_GetError().
1.1969 +**************************************************************************
1.1970 +*/
1.1971 +NSPR_API(PRInt32) PR_Poll(
1.1972 + PRPollDesc *pds, PRIntn npds, PRIntervalTime timeout);
1.1973 +
1.1974 +/*
1.1975 +**************************************************************************
1.1976 +**
1.1977 +** Pollable events
1.1978 +**
1.1979 +** A pollable event is a special kind of file descriptor.
1.1980 +** The only I/O operation you can perform on a pollable event
1.1981 +** is to poll it with the PR_POLL_READ flag. You can't
1.1982 +** read from or write to a pollable event.
1.1983 +**
1.1984 +** The purpose of a pollable event is to combine event waiting
1.1985 +** with I/O waiting in a single PR_Poll call. Pollable events
1.1986 +** are implemented using a pipe or a pair of TCP sockets
1.1987 +** connected via the loopback address, therefore setting and
1.1988 +** waiting for pollable events are expensive operating system
1.1989 +** calls. Do not use pollable events for general thread
1.1990 +** synchronization. Use condition variables instead.
1.1991 +**
1.1992 +** A pollable event has two states: set and unset. Events
1.1993 +** are not queued, so there is no notion of an event count.
1.1994 +** A pollable event is either set or unset.
1.1995 +**
1.1996 +** A new pollable event is created by a PR_NewPollableEvent
1.1997 +** call and is initially in the unset state.
1.1998 +**
1.1999 +** PR_WaitForPollableEvent blocks the calling thread until
1.2000 +** the pollable event is set, and then it atomically unsets
1.2001 +** the pollable event before it returns.
1.2002 +**
1.2003 +** To set a pollable event, call PR_SetPollableEvent.
1.2004 +**
1.2005 +** One can call PR_Poll with the PR_POLL_READ flag on a pollable
1.2006 +** event. When the pollable event is set, PR_Poll returns with
1.2007 +** the PR_POLL_READ flag set in the out_flags.
1.2008 +**
1.2009 +** To close a pollable event, call PR_DestroyPollableEvent
1.2010 +** (not PR_Close).
1.2011 +**
1.2012 +**************************************************************************
1.2013 +*/
1.2014 +
1.2015 +NSPR_API(PRFileDesc *) PR_NewPollableEvent(void);
1.2016 +
1.2017 +NSPR_API(PRStatus) PR_DestroyPollableEvent(PRFileDesc *event);
1.2018 +
1.2019 +NSPR_API(PRStatus) PR_SetPollableEvent(PRFileDesc *event);
1.2020 +
1.2021 +NSPR_API(PRStatus) PR_WaitForPollableEvent(PRFileDesc *event);
1.2022 +
1.2023 +PR_END_EXTERN_C
1.2024 +
1.2025 +#endif /* prio_h___ */
