Back to index

lightning-sunbird  0.9+nobinonly
prio.h
Go to the documentation of this file.
00001 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
00002 /* ***** BEGIN LICENSE BLOCK *****
00003  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00004  *
00005  * The contents of this file are subject to the Mozilla Public License Version
00006  * 1.1 (the "License"); you may not use this file except in compliance with
00007  * the License. You may obtain a copy of the License at
00008  * http://www.mozilla.org/MPL/
00009  *
00010  * Software distributed under the License is distributed on an "AS IS" basis,
00011  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00012  * for the specific language governing rights and limitations under the
00013  * License.
00014  *
00015  * The Original Code is the Netscape Portable Runtime (NSPR).
00016  *
00017  * The Initial Developer of the Original Code is
00018  * Netscape Communications Corporation.
00019  * Portions created by the Initial Developer are Copyright (C) 1998-2000
00020  * the Initial Developer. All Rights Reserved.
00021  *
00022  * Contributor(s):
00023  *
00024  * Alternatively, the contents of this file may be used under the terms of
00025  * either the GNU General Public License Version 2 or later (the "GPL"), or
00026  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00027  * in which case the provisions of the GPL or the LGPL are applicable instead
00028  * of those above. If you wish to allow use of your version of this file only
00029  * under the terms of either the GPL or the LGPL, and not to allow others to
00030  * use your version of this file under the terms of the MPL, indicate your
00031  * decision by deleting the provisions above and replace them with the notice
00032  * and other provisions required by the GPL or the LGPL. If you do not delete
00033  * the provisions above, a recipient may use your version of this file under
00034  * the terms of any one of the MPL, the GPL or the LGPL.
00035  *
00036  * ***** END LICENSE BLOCK ***** */
00037 
00038 /*
00039  * File:     prio.h
00040  *
00041  * Description:    PR i/o related stuff, such as file system access, file
00042  *         i/o, socket i/o, etc.
00043  */
00044 
00045 #ifndef prio_h___
00046 #define prio_h___
00047 
00048 #include "prlong.h"
00049 #include "prtime.h"
00050 #include "prinrval.h"
00051 #include "prinet.h"
00052 
00053 PR_BEGIN_EXTERN_C
00054 
00055 /* Typedefs */
00056 typedef struct PRDir            PRDir;
00057 typedef struct PRDirEntry       PRDirEntry;
00058 #ifdef MOZ_UNICODE
00059 typedef struct PRDirUTF16       PRDirUTF16;
00060 typedef struct PRDirEntryUTF16  PRDirEntryUTF16;
00061 #endif /* MOZ_UNICODE */
00062 typedef struct PRFileDesc       PRFileDesc;
00063 typedef struct PRFileInfo       PRFileInfo;
00064 typedef struct PRFileInfo64     PRFileInfo64;
00065 typedef union  PRNetAddr        PRNetAddr;
00066 typedef struct PRIOMethods      PRIOMethods;
00067 typedef struct PRPollDesc       PRPollDesc;
00068 typedef struct PRFilePrivate    PRFilePrivate;
00069 typedef struct PRSendFileData   PRSendFileData;
00070 
00071 /*
00072 ***************************************************************************
00073 ** The file descriptor.
00074 ** This is the primary structure to represent any active open socket,
00075 ** whether it be a normal file or a network connection. Such objects
00076 ** are stackable (or layerable). Each layer may have its own set of
00077 ** method pointers and context private to that layer. All each layer
00078 ** knows about its neighbors is how to get to their method table.
00079 ***************************************************************************
00080 */
00081 
00082 typedef PRIntn PRDescIdentity;          /* see: Layering file descriptors */
00083 
00084 struct PRFileDesc {
00085     const PRIOMethods *methods;         /* the I/O methods table */
00086     PRFilePrivate *secret;              /* layer dependent data */
00087     PRFileDesc *lower, *higher;         /* pointers to adjacent layers */
00088     void (PR_CALLBACK *dtor)(PRFileDesc *fd);
00089                                         /* A destructor function for layer */
00090     PRDescIdentity identity;            /* Identity of this particular layer  */
00091 };
00092 
00093 /*
00094 ***************************************************************************
00095 ** PRTransmitFileFlags
00096 **
00097 ** Flags for PR_TransmitFile.  Pass PR_TRANSMITFILE_CLOSE_SOCKET to
00098 ** PR_TransmitFile if the connection should be closed after the file
00099 ** is transmitted.
00100 ***************************************************************************
00101 */
00102 typedef enum PRTransmitFileFlags {
00103     PR_TRANSMITFILE_KEEP_OPEN = 0,    /* socket is left open after file
00104                                        * is transmitted. */
00105     PR_TRANSMITFILE_CLOSE_SOCKET = 1  /* socket is closed after file
00106                                        * is transmitted. */
00107 } PRTransmitFileFlags;
00108 
00109 /*
00110 **************************************************************************
00111 ** Macros for PRNetAddr
00112 **
00113 ** Address families: PR_AF_INET, PR_AF_INET6, PR_AF_LOCAL
00114 ** IP addresses: PR_INADDR_ANY, PR_INADDR_LOOPBACK, PR_INADDR_BROADCAST
00115 **************************************************************************
00116 */
00117 
00118 #ifdef WIN32
00119 
00120 #define PR_AF_INET 2
00121 #define PR_AF_LOCAL 1
00122 #define PR_INADDR_ANY (unsigned long)0x00000000
00123 #define PR_INADDR_LOOPBACK 0x7f000001
00124 #define PR_INADDR_BROADCAST (unsigned long)0xffffffff
00125 
00126 #else /* WIN32 */
00127 
00128 #define PR_AF_INET AF_INET
00129 #define PR_AF_LOCAL AF_UNIX
00130 #define PR_INADDR_ANY INADDR_ANY
00131 #define PR_INADDR_LOOPBACK INADDR_LOOPBACK
00132 #define PR_INADDR_BROADCAST INADDR_BROADCAST
00133 
00134 #endif /* WIN32 */
00135 
00136 /*
00137 ** Define PR_AF_INET6 in prcpucfg.h with the same
00138 ** value as AF_INET6 on platforms with IPv6 support.
00139 ** Otherwise define it here.
00140 */
00141 #ifndef PR_AF_INET6
00142 #define PR_AF_INET6 100
00143 #endif
00144 
00145 #ifndef PR_AF_UNSPEC
00146 #define PR_AF_UNSPEC 0
00147 #endif
00148 
00149 /*
00150 **************************************************************************
00151 ** A network address
00152 **
00153 ** Only Internet Protocol (IPv4 and IPv6) addresses are supported.
00154 ** The address family must always represent IPv4 (AF_INET, probably == 2)
00155 ** or IPv6 (AF_INET6).
00156 **************************************************************************
00157 *************************************************************************/
00158 
00159 struct PRIPv6Addr {
00160        union {
00161               PRUint8  _S6_u8[16];
00162               PRUint16 _S6_u16[8];
00163               PRUint32 _S6_u32[4];
00164               PRUint64 _S6_u64[2];
00165        } _S6_un;
00166 };
00167 #define pr_s6_addr          _S6_un._S6_u8
00168 #define pr_s6_addr16 _S6_un._S6_u16
00169 #define pr_s6_addr32 _S6_un._S6_u32
00170 #define pr_s6_addr64        _S6_un._S6_u64
00171 
00172 typedef struct PRIPv6Addr PRIPv6Addr;
00173 
00174 union PRNetAddr {
00175     struct {
00176         PRUint16 family;                /* address family (0x00ff maskable) */
00177 #ifdef XP_BEOS
00178         char data[10];                  /* Be has a smaller structure */
00179 #else
00180         char data[14];                  /* raw address data */
00181 #endif
00182     } raw;
00183     struct {
00184         PRUint16 family;                /* address family (AF_INET) */
00185         PRUint16 port;                  /* port number */
00186         PRUint32 ip;                    /* The actual 32 bits of address */
00187 #ifdef XP_BEOS
00188         char pad[4];                    /* Be has a smaller structure */
00189 #else
00190         char pad[8];
00191 #endif
00192     } inet;
00193     struct {
00194         PRUint16 family;                /* address family (AF_INET6) */
00195         PRUint16 port;                  /* port number */
00196         PRUint32 flowinfo;              /* routing information */
00197         PRIPv6Addr ip;                  /* the actual 128 bits of address */
00198         PRUint32 scope_id;              /* set of interfaces for a scope */
00199     } ipv6;
00200 #if defined(XP_UNIX) || defined(XP_OS2_EMX)
00201     struct {                            /* Unix domain socket address */
00202         PRUint16 family;                /* address family (AF_UNIX) */
00203 #ifdef XP_OS2
00204         char path[108];                 /* null-terminated pathname */
00205                                         /* bind fails if size is not 108. */
00206 #else
00207         char path[104];                 /* null-terminated pathname */
00208 #endif
00209     } local;
00210 #endif
00211 };
00212 
00213 /*
00214 ***************************************************************************
00215 ** PRSockOption
00216 **
00217 ** The file descriptors can have predefined options set after they file
00218 ** descriptor is created to change their behavior. Only the options in
00219 ** the following enumeration are supported.
00220 ***************************************************************************
00221 */
00222 typedef enum PRSockOption
00223 {
00224     PR_SockOpt_Nonblocking,     /* nonblocking io */
00225     PR_SockOpt_Linger,          /* linger on close if data present */
00226     PR_SockOpt_Reuseaddr,       /* allow local address reuse */
00227     PR_SockOpt_Keepalive,       /* keep connections alive */
00228     PR_SockOpt_RecvBufferSize,  /* send buffer size */
00229     PR_SockOpt_SendBufferSize,  /* receive buffer size */
00230 
00231     PR_SockOpt_IpTimeToLive,    /* time to live */
00232     PR_SockOpt_IpTypeOfService, /* type of service and precedence */
00233 
00234     PR_SockOpt_AddMember,       /* add an IP group membership */
00235     PR_SockOpt_DropMember,      /* drop an IP group membership */
00236     PR_SockOpt_McastInterface,  /* multicast interface address */
00237     PR_SockOpt_McastTimeToLive, /* multicast timetolive */
00238     PR_SockOpt_McastLoopback,   /* multicast loopback */
00239 
00240     PR_SockOpt_NoDelay,         /* don't delay send to coalesce packets */
00241     PR_SockOpt_MaxSegment,      /* maximum segment size */
00242     PR_SockOpt_Broadcast,       /* enable broadcast */
00243     PR_SockOpt_Last
00244 } PRSockOption;
00245 
00246 typedef struct PRLinger {
00247        PRBool polarity;                /* Polarity of the option's setting */
00248        PRIntervalTime linger;          /* Time to linger before closing */
00249 } PRLinger;
00250 
00251 typedef struct PRMcastRequest {
00252        PRNetAddr mcaddr;                  /* IP multicast address of group */
00253        PRNetAddr ifaddr;                  /* local IP address of interface */
00254 } PRMcastRequest;
00255 
00256 typedef struct PRSocketOptionData
00257 {
00258     PRSockOption option;
00259     union
00260     {
00261         PRUintn ip_ttl;             /* IP time to live */
00262         PRUintn mcast_ttl;          /* IP multicast time to live */
00263         PRUintn tos;                /* IP type of service and precedence */
00264         PRBool non_blocking;        /* Non-blocking (network) I/O */
00265         PRBool reuse_addr;          /* Allow local address reuse */
00266         PRBool keep_alive;          /* Keep connections alive */
00267         PRBool mcast_loopback;      /* IP multicast loopback */
00268         PRBool no_delay;            /* Don't delay send to coalesce packets */
00269         PRBool broadcast;           /* Enable broadcast */
00270         PRSize max_segment;         /* Maximum segment size */
00271         PRSize recv_buffer_size;    /* Receive buffer size */
00272         PRSize send_buffer_size;    /* Send buffer size */
00273         PRLinger linger;            /* Time to linger on close if data present */
00274         PRMcastRequest add_member;  /* add an IP group membership */
00275         PRMcastRequest drop_member; /* Drop an IP group membership */
00276         PRNetAddr mcast_if;         /* multicast interface address */
00277     } value;
00278 } PRSocketOptionData;
00279 
00280 /*
00281 ***************************************************************************
00282 ** PRIOVec
00283 **
00284 ** The I/O vector is used by the write vector method to describe the areas
00285 ** that are affected by the ouput operation.
00286 ***************************************************************************
00287 */
00288 typedef struct PRIOVec {
00289     char *iov_base;
00290     int iov_len;
00291 } PRIOVec;
00292 
00293 /*
00294 ***************************************************************************
00295 ** Discover what type of socket is being described by the file descriptor.
00296 ***************************************************************************
00297 */
00298 typedef enum PRDescType
00299 {
00300     PR_DESC_FILE = 1,
00301     PR_DESC_SOCKET_TCP = 2,
00302     PR_DESC_SOCKET_UDP = 3,
00303     PR_DESC_LAYERED = 4,
00304     PR_DESC_PIPE = 5
00305 } PRDescType;
00306 
00307 typedef enum PRSeekWhence {
00308     PR_SEEK_SET = 0,
00309     PR_SEEK_CUR = 1,
00310     PR_SEEK_END = 2
00311 } PRSeekWhence;
00312 
00313 NSPR_API(PRDescType) PR_GetDescType(PRFileDesc *file);
00314 
00315 /*
00316 ***************************************************************************
00317 ** PRIOMethods
00318 **
00319 ** The I/O methods table provides procedural access to the functions of
00320 ** the file descriptor. It is the responsibility of a layer implementor
00321 ** to provide suitable functions at every entry point. If a layer provides
00322 ** no functionality, it should call the next lower(higher) function of the
00323 ** same name (e.g., return fd->lower->method->close(fd->lower));
00324 **
00325 ** Not all functions are implemented for all types of files. In cases where
00326 ** that is true, the function will return a error indication with an error
00327 ** code of PR_INVALID_METHOD_ERROR.
00328 ***************************************************************************
00329 */
00330 
00331 typedef PRStatus (PR_CALLBACK *PRCloseFN)(PRFileDesc *fd);
00332 typedef PRInt32 (PR_CALLBACK *PRReadFN)(PRFileDesc *fd, void *buf, PRInt32 amount);
00333 typedef PRInt32 (PR_CALLBACK *PRWriteFN)(PRFileDesc *fd, const void *buf, PRInt32 amount);
00334 typedef PRInt32 (PR_CALLBACK *PRAvailableFN)(PRFileDesc *fd);
00335 typedef PRInt64 (PR_CALLBACK *PRAvailable64FN)(PRFileDesc *fd);
00336 typedef PRStatus (PR_CALLBACK *PRFsyncFN)(PRFileDesc *fd);
00337 typedef PROffset32 (PR_CALLBACK *PRSeekFN)(PRFileDesc *fd, PROffset32 offset, PRSeekWhence how);
00338 typedef PROffset64 (PR_CALLBACK *PRSeek64FN)(PRFileDesc *fd, PROffset64 offset, PRSeekWhence how);
00339 typedef PRStatus (PR_CALLBACK *PRFileInfoFN)(PRFileDesc *fd, PRFileInfo *info);
00340 typedef PRStatus (PR_CALLBACK *PRFileInfo64FN)(PRFileDesc *fd, PRFileInfo64 *info);
00341 typedef PRInt32 (PR_CALLBACK *PRWritevFN)(
00342     PRFileDesc *fd, const PRIOVec *iov, PRInt32 iov_size,
00343     PRIntervalTime timeout);
00344 typedef PRStatus (PR_CALLBACK *PRConnectFN)(
00345     PRFileDesc *fd, const PRNetAddr *addr, PRIntervalTime timeout);
00346 typedef PRFileDesc* (PR_CALLBACK *PRAcceptFN) (
00347     PRFileDesc *fd, PRNetAddr *addr, PRIntervalTime timeout);
00348 typedef PRStatus (PR_CALLBACK *PRBindFN)(PRFileDesc *fd, const PRNetAddr *addr);
00349 typedef PRStatus (PR_CALLBACK *PRListenFN)(PRFileDesc *fd, PRIntn backlog);
00350 typedef PRStatus (PR_CALLBACK *PRShutdownFN)(PRFileDesc *fd, PRIntn how);
00351 typedef PRInt32 (PR_CALLBACK *PRRecvFN)(
00352     PRFileDesc *fd, void *buf, PRInt32 amount,
00353     PRIntn flags, PRIntervalTime timeout);
00354 typedef PRInt32 (PR_CALLBACK *PRSendFN) (
00355     PRFileDesc *fd, const void *buf, PRInt32 amount,
00356     PRIntn flags, PRIntervalTime timeout);
00357 typedef PRInt32 (PR_CALLBACK *PRRecvfromFN)(
00358     PRFileDesc *fd, void *buf, PRInt32 amount,
00359     PRIntn flags, PRNetAddr *addr, PRIntervalTime timeout);
00360 typedef PRInt32 (PR_CALLBACK *PRSendtoFN)(
00361     PRFileDesc *fd, const void *buf, PRInt32 amount,
00362     PRIntn flags, const PRNetAddr *addr, PRIntervalTime timeout);
00363 typedef PRInt16 (PR_CALLBACK *PRPollFN)(
00364     PRFileDesc *fd, PRInt16 in_flags, PRInt16 *out_flags);
00365 typedef PRInt32 (PR_CALLBACK *PRAcceptreadFN)(
00366     PRFileDesc *sd, PRFileDesc **nd, PRNetAddr **raddr,
00367     void *buf, PRInt32 amount, PRIntervalTime t);
00368 typedef PRInt32 (PR_CALLBACK *PRTransmitfileFN)(
00369      PRFileDesc *sd, PRFileDesc *fd, const void *headers,
00370      PRInt32 hlen, PRTransmitFileFlags flags, PRIntervalTime t);
00371 typedef PRStatus (PR_CALLBACK *PRGetsocknameFN)(PRFileDesc *fd, PRNetAddr *addr);
00372 typedef PRStatus (PR_CALLBACK *PRGetpeernameFN)(PRFileDesc *fd, PRNetAddr *addr);
00373 typedef PRStatus (PR_CALLBACK *PRGetsocketoptionFN)(
00374     PRFileDesc *fd, PRSocketOptionData *data);
00375 typedef PRStatus (PR_CALLBACK *PRSetsocketoptionFN)(
00376     PRFileDesc *fd, const PRSocketOptionData *data);
00377 typedef PRInt32 (PR_CALLBACK *PRSendfileFN)(
00378        PRFileDesc *networkSocket, PRSendFileData *sendData,
00379        PRTransmitFileFlags flags, PRIntervalTime timeout);
00380 typedef PRStatus (PR_CALLBACK *PRConnectcontinueFN)(
00381     PRFileDesc *fd, PRInt16 out_flags);
00382 typedef PRIntn (PR_CALLBACK *PRReservedFN)(PRFileDesc *fd);
00383 
00384 struct PRIOMethods {
00385     PRDescType file_type;           /* Type of file represented (tos)           */
00386     PRCloseFN close;                /* close file and destroy descriptor        */
00387     PRReadFN read;                  /* read up to specified bytes into buffer   */
00388     PRWriteFN write;                /* write specified bytes from buffer        */
00389     PRAvailableFN available;        /* determine number of bytes available      */
00390     PRAvailable64FN available64;    /*          ditto, 64 bit                   */
00391     PRFsyncFN fsync;                /* flush all buffers to permanent store     */
00392     PRSeekFN seek;                  /* position the file to the desired place   */
00393     PRSeek64FN seek64;              /*           ditto, 64 bit                  */
00394     PRFileInfoFN fileInfo;          /* Get information about an open file       */
00395     PRFileInfo64FN fileInfo64;      /*           ditto, 64 bit                  */
00396     PRWritevFN writev;              /* Write segments as described by iovector  */
00397     PRConnectFN connect;            /* Connect to the specified (net) address   */
00398     PRAcceptFN accept;              /* Accept a connection for a (net) peer     */
00399     PRBindFN bind;                  /* Associate a (net) address with the fd    */
00400     PRListenFN listen;              /* Prepare to listen for (net) connections  */
00401     PRShutdownFN shutdown;          /* Shutdown a (net) connection              */
00402     PRRecvFN recv;                  /* Solicit up the the specified bytes       */
00403     PRSendFN send;                  /* Send all the bytes specified             */
00404     PRRecvfromFN recvfrom;          /* Solicit (net) bytes and report source    */
00405     PRSendtoFN sendto;              /* Send bytes to (net) address specified    */
00406     PRPollFN poll;                  /* Test the fd to see if it is ready        */
00407     PRAcceptreadFN acceptread;      /* Accept and read on a new (net) fd        */
00408     PRTransmitfileFN transmitfile;  /* Transmit at entire file                  */
00409     PRGetsocknameFN getsockname;    /* Get (net) address associated with fd     */
00410     PRGetpeernameFN getpeername;    /* Get peer's (net) address                 */
00411     PRReservedFN reserved_fn_6;     /* reserved for future use */
00412     PRReservedFN reserved_fn_5;     /* reserved for future use */
00413     PRGetsocketoptionFN getsocketoption;
00414                                     /* Get current setting of specified option  */
00415     PRSetsocketoptionFN setsocketoption;
00416                                     /* Set value of specified option            */
00417     PRSendfileFN sendfile;                /* Send a (partial) file with header/trailer*/
00418     PRConnectcontinueFN connectcontinue;
00419                                     /* Continue a nonblocking connect */
00420     PRReservedFN reserved_fn_3;           /* reserved for future use */
00421     PRReservedFN reserved_fn_2;           /* reserved for future use */
00422     PRReservedFN reserved_fn_1;           /* reserved for future use */
00423     PRReservedFN reserved_fn_0;           /* reserved for future use */
00424 };
00425 
00426 /*
00427  **************************************************************************
00428  * FUNCTION: PR_GetSpecialFD
00429  * DESCRIPTION: Get the file descriptor that represents the standard input,
00430  *              output, or error stream.
00431  * INPUTS:
00432  *     PRSpecialFD id
00433  *         A value indicating the type of stream desired:
00434  *             PR_StandardInput: standard input
00435  *             PR_StandardOuput: standard output
00436  *             PR_StandardError: standard error
00437  * OUTPUTS: none
00438  * RETURNS: PRFileDesc *
00439  *     If the argument is valid, PR_GetSpecialFD returns a file descriptor
00440  *     that represents the corresponding standard I/O stream.  Otherwise,
00441  *     PR_GetSpecialFD returns NULL and sets error PR_INVALID_ARGUMENT_ERROR.
00442  **************************************************************************
00443  */
00444 
00445 typedef enum PRSpecialFD
00446 {
00447     PR_StandardInput,          /* standard input */
00448     PR_StandardOutput,         /* standard output */
00449     PR_StandardError           /* standard error */
00450 } PRSpecialFD;
00451 
00452 NSPR_API(PRFileDesc*) PR_GetSpecialFD(PRSpecialFD id);
00453 
00454 #define PR_STDIN     PR_GetSpecialFD(PR_StandardInput)
00455 #define PR_STDOUT    PR_GetSpecialFD(PR_StandardOutput)
00456 #define PR_STDERR    PR_GetSpecialFD(PR_StandardError)
00457 
00458 /*
00459  **************************************************************************
00460  * Layering file descriptors
00461  *
00462  * File descriptors may be layered. Each layer has it's own identity.
00463  * Identities are allocated by the runtime and are to be associated
00464  * (by the layer implementor) with all layers that are of that type.
00465  * It is then possible to scan the chain of layers and find a layer
00466  * that one recongizes and therefore predict that it will implement
00467  * a desired protocol.
00468  *
00469  * There are three well-known identities:
00470  *      PR_INVALID_IO_LAYER => an invalid layer identity, for error return
00471  *      PR_TOP_IO_LAYER     => the identity of the top of the stack
00472  *      PR_NSPR_IO_LAYER    => the identity used by NSPR proper
00473  * PR_TOP_IO_LAYER may be used as a shorthand for identifying the topmost
00474  * layer of an existing stack. Ie., the following two constructs are
00475  * equivalent.
00476  *
00477  *      rv = PR_PushIOLayer(stack, PR_TOP_IO_LAYER, my_layer);
00478  *      rv = PR_PushIOLayer(stack, PR_GetLayersIdentity(stack), my_layer)
00479  *
00480  * A string may be associated with the creation of the identity. It
00481  * will be copied by the runtime. If queried the runtime will return
00482  * a reference to that copied string (not yet another copy). There
00483  * is no facility for deleting an identity.
00484  **************************************************************************
00485  */
00486 
00487 #define PR_IO_LAYER_HEAD (PRDescIdentity)-3
00488 #define PR_INVALID_IO_LAYER (PRDescIdentity)-1
00489 #define PR_TOP_IO_LAYER (PRDescIdentity)-2
00490 #define PR_NSPR_IO_LAYER (PRDescIdentity)0
00491 
00492 NSPR_API(PRDescIdentity) PR_GetUniqueIdentity(const char *layer_name);
00493 NSPR_API(const char*) PR_GetNameForIdentity(PRDescIdentity ident);
00494 NSPR_API(PRDescIdentity) PR_GetLayersIdentity(PRFileDesc* fd);
00495 NSPR_API(PRFileDesc*) PR_GetIdentitiesLayer(PRFileDesc* fd_stack, PRDescIdentity id);
00496 
00497 /*
00498  **************************************************************************
00499  * PR_GetDefaultIOMethods: Accessing the default methods table.
00500  * You may get a pointer to the default methods table by calling this function.
00501  * You may then select any elements from that table with which to build your
00502  * layer's methods table. You may NOT modify the table directly.
00503  **************************************************************************
00504  */
00505 NSPR_API(const PRIOMethods *) PR_GetDefaultIOMethods(void);
00506 
00507 /*
00508  **************************************************************************
00509  * Creating a layer
00510  *
00511  * A new layer may be allocated by calling PR_CreateIOLayerStub(). The
00512  * file descriptor returned will contain the pointer to the methods table
00513  * provided. The runtime will not modify the table nor test its correctness.
00514  **************************************************************************
00515  */
00516 NSPR_API(PRFileDesc*) PR_CreateIOLayerStub(
00517     PRDescIdentity ident, const PRIOMethods *methods);
00518 
00519 /*
00520  **************************************************************************
00521  * Creating a layer
00522  *
00523  * A new stack may be created by calling PR_CreateIOLayer(). The
00524  * file descriptor returned will point to the top of the stack, which has
00525  * the layer 'fd' as the topmost layer.
00526  * 
00527  * NOTE: This function creates a new style stack, which has a fixed, dummy
00528  * header. The old style stack, created by a call to PR_PushIOLayer,
00529  * results in modifying contents of the top layer of the stack, when
00530  * pushing and popping layers of the stack.
00531  **************************************************************************
00532  */
00533 NSPR_API(PRFileDesc*) PR_CreateIOLayer(PRFileDesc* fd);
00534 
00535 /*
00536  **************************************************************************
00537  * Pushing a layer
00538  *
00539  * A file descriptor (perhaps allocated using PR_CreateIOLayerStub()) may
00540  * be pushed into an existing stack of file descriptors at any point the
00541  * caller deems appropriate. The new layer will be inserted into the stack
00542  * just above the layer with the indicated identity.
00543  *
00544  * Note: Even if the identity parameter indicates the top-most layer of
00545  * the stack, the value of the file descriptor describing the original
00546  * stack will not change.
00547  **************************************************************************
00548  */
00549 NSPR_API(PRStatus) PR_PushIOLayer(
00550     PRFileDesc *fd_stack, PRDescIdentity id, PRFileDesc *layer);
00551 
00552 /*
00553  **************************************************************************
00554  * Popping a layer
00555  *
00556  * A layer may be popped from a stack by indicating the identity of the
00557  * layer to be removed. If found, a pointer to the removed object will
00558  * be returned to the caller. The object then becomes the responsibility
00559  * of the caller.
00560  *
00561  * Note: Even if the identity indicates the top layer of the stack, the
00562  * reference returned will not be the file descriptor for the stack and
00563  * that file descriptor will remain valid.
00564  **************************************************************************
00565  */
00566 NSPR_API(PRFileDesc*) PR_PopIOLayer(PRFileDesc *fd_stack, PRDescIdentity id);
00567 
00568 /*
00569  **************************************************************************
00570  * FUNCTION:    PR_Open
00571  * DESCRIPTION:    Open a file for reading, writing, or both.
00572  * INPUTS:
00573  *     const char *name
00574  *         The path name of the file to be opened
00575  *     PRIntn flags
00576  *         The file status flags.
00577  *         It is a bitwise OR of the following bit flags (only one of
00578  *         the first three flags below may be used):
00579  *            PR_RDONLY        Open for reading only.
00580  *            PR_WRONLY        Open for writing only.
00581  *            PR_RDWR          Open for reading and writing.
00582  *            PR_CREATE_FILE   If the file does not exist, the file is created
00583  *                              If the file exists, this flag has no effect.
00584  *      PR_SYNC          If set, each write will wait for both the file data
00585  *                              and file status to be physically updated.
00586  *            PR_APPEND        The file pointer is set to the end of
00587  *                              the file prior to each write.
00588  *            PR_TRUNCATE      If the file exists, its length is truncated to 0.
00589  *      PR_EXCL          With PR_CREATE_FILE, if the file does not exist,
00590  *                              the file is created. If the file already 
00591  *                              exists, no action and NULL is returned
00592  *
00593  *     PRIntn mode
00594  *         The access permission bits of the file mode, if the file is
00595  *         created when PR_CREATE_FILE is on.
00596  * OUTPUTS:    None
00597  * RETURNS:    PRFileDesc *
00598  *     If the file is successfully opened,
00599  *     returns a pointer to the PRFileDesc
00600  *     created for the newly opened file.
00601  *     Returns a NULL pointer if the open
00602  *     failed.
00603  * SIDE EFFECTS:
00604  * RESTRICTIONS:
00605  * MEMORY:
00606  *     The return value, if not NULL, points to a dynamically allocated
00607  *     PRFileDesc object.
00608  * ALGORITHM:
00609  **************************************************************************
00610  */
00611 
00612 /* Open flags */
00613 #define PR_RDONLY       0x01
00614 #define PR_WRONLY       0x02
00615 #define PR_RDWR         0x04
00616 #define PR_CREATE_FILE  0x08
00617 #define PR_APPEND       0x10
00618 #define PR_TRUNCATE     0x20
00619 #define PR_SYNC         0x40
00620 #define PR_EXCL         0x80
00621 
00622 /*
00623 ** File modes ....
00624 **
00625 ** CAVEAT: 'mode' is currently only applicable on UNIX platforms.
00626 ** The 'mode' argument may be ignored by PR_Open on other platforms.
00627 **
00628 **   00400   Read by owner.
00629 **   00200   Write by owner.
00630 **   00100   Execute (search if a directory) by owner.
00631 **   00040   Read by group.
00632 **   00020   Write by group.
00633 **   00010   Execute by group.
00634 **   00004   Read by others.
00635 **   00002   Write by others
00636 **   00001   Execute by others.
00637 **
00638 */
00639 
00640 NSPR_API(PRFileDesc*) PR_Open(const char *name, PRIntn flags, PRIntn mode);
00641 
00642 /*
00643  **************************************************************************
00644  * FUNCTION: PR_OpenFile
00645  * DESCRIPTION:
00646  *     Open a file for reading, writing, or both.
00647  *     PR_OpenFile has the same prototype as PR_Open but implements
00648  *     the specified file mode where possible.
00649  **************************************************************************
00650  */
00651 
00652 /* File mode bits */
00653 #define PR_IRWXU 00700  /* read, write, execute/search by owner */
00654 #define PR_IRUSR 00400  /* read permission, owner */
00655 #define PR_IWUSR 00200  /* write permission, owner */
00656 #define PR_IXUSR 00100  /* execute/search permission, owner */
00657 #define PR_IRWXG 00070  /* read, write, execute/search by group */
00658 #define PR_IRGRP 00040  /* read permission, group */
00659 #define PR_IWGRP 00020  /* write permission, group */
00660 #define PR_IXGRP 00010  /* execute/search permission, group */
00661 #define PR_IRWXO 00007  /* read, write, execute/search by others */
00662 #define PR_IROTH 00004  /* read permission, others */
00663 #define PR_IWOTH 00002  /* write permission, others */
00664 #define PR_IXOTH 00001  /* execute/search permission, others */
00665 
00666 NSPR_API(PRFileDesc*) PR_OpenFile(
00667     const char *name, PRIntn flags, PRIntn mode);
00668 
00669 #ifdef MOZ_UNICODE
00670 /*
00671  * EXPERIMENTAL: This function may be removed in a future release.
00672  */
00673 NSPR_API(PRFileDesc*) PR_OpenFileUTF16(
00674     const PRUnichar *name, PRIntn flags, PRIntn mode);
00675 #endif /* MOZ_UNICODE */
00676 
00677 /*
00678  **************************************************************************
00679  * FUNCTION: PR_Close
00680  * DESCRIPTION:
00681  *     Close a file or socket.
00682  * INPUTS:
00683  *     PRFileDesc *fd
00684  *         a pointer to a PRFileDesc.
00685  * OUTPUTS:
00686  *     None.
00687  * RETURN:
00688  *     PRStatus
00689  * SIDE EFFECTS:
00690  * RESTRICTIONS:
00691  *     None.
00692  * MEMORY:
00693  *     The dynamic memory pointed to by the argument fd is freed.
00694  **************************************************************************
00695  */
00696 
00697 NSPR_API(PRStatus)    PR_Close(PRFileDesc *fd);
00698 
00699 /*
00700  **************************************************************************
00701  * FUNCTION: PR_Read
00702  * DESCRIPTION:
00703  *     Read bytes from a file or socket.
00704  *     The operation will block until either an end of stream indication is
00705  *     encountered, some positive number of bytes are transferred, or there
00706  *     is an error. No more than 'amount' bytes will be transferred.
00707  * INPUTS:
00708  *     PRFileDesc *fd
00709  *         pointer to the PRFileDesc object for the file or socket
00710  *     void *buf
00711  *         pointer to a buffer to hold the data read in.
00712  *     PRInt32 amount
00713  *         the size of 'buf' (in bytes)
00714  * OUTPUTS:
00715  * RETURN:
00716  *     PRInt32
00717  *         a positive number indicates the number of bytes actually read in.
00718  *         0 means end of file is reached or the network connection is closed.
00719  *         -1 indicates a failure. The reason for the failure is obtained
00720  *         by calling PR_GetError().
00721  * SIDE EFFECTS:
00722  *     data is written into the buffer pointed to by 'buf'.
00723  * RESTRICTIONS:
00724  *     None.
00725  * MEMORY:
00726  *     N/A
00727  * ALGORITHM:
00728  *     N/A
00729  **************************************************************************
00730  */
00731 
00732 NSPR_API(PRInt32) PR_Read(PRFileDesc *fd, void *buf, PRInt32 amount);
00733 
00734 /*
00735  ***************************************************************************
00736  * FUNCTION: PR_Write
00737  * DESCRIPTION:
00738  *     Write a specified number of bytes to a file or socket.  The thread
00739  *     invoking this function blocks until all the data is written.
00740  * INPUTS:
00741  *     PRFileDesc *fd
00742  *         pointer to a PRFileDesc object that refers to a file or socket
00743  *     const void *buf
00744  *         pointer to the buffer holding the data
00745  *     PRInt32 amount
00746  *         amount of data in bytes to be written from the buffer
00747  * OUTPUTS:
00748  *     None.
00749  * RETURN: PRInt32
00750  *     A positive number indicates the number of bytes successfully written.
00751  *     A -1 is an indication that the operation failed. The reason
00752  *     for the failure is obtained by calling PR_GetError().
00753  ***************************************************************************
00754  */
00755 
00756 NSPR_API(PRInt32) PR_Write(PRFileDesc *fd,const void *buf,PRInt32 amount);
00757 
00758 /*
00759  ***************************************************************************
00760  * FUNCTION: PR_Writev
00761  * DESCRIPTION:
00762  *     Write data to a socket.  The data is organized in a PRIOVec array. The
00763  *     operation will block until all the data is written or the operation
00764  *     fails.
00765  * INPUTS:
00766  *     PRFileDesc *fd
00767  *         Pointer that points to a PRFileDesc object for a socket.
00768  *     const PRIOVec *iov
00769  *         An array of PRIOVec.  PRIOVec is a struct with the following
00770  *         two fields:
00771  *             char *iov_base;
00772  *             int iov_len;
00773  *     PRInt32 iov_size
00774  *         Number of elements in the iov array. The value of this
00775  *         argument must not be greater than PR_MAX_IOVECTOR_SIZE.
00776  *         If it is, the method will fail (PR_BUFFER_OVERFLOW_ERROR).
00777  *     PRIntervalTime timeout
00778  *       Time limit for completion of the entire write operation.
00779  * OUTPUTS:
00780  *     None
00781  * RETURN:
00782  *     A positive number indicates the number of bytes successfully written.
00783  *     A -1 is an indication that the operation failed. The reason
00784  *     for the failure is obtained by calling PR_GetError().
00785  ***************************************************************************
00786  */
00787 
00788 #define PR_MAX_IOVECTOR_SIZE 16   /* 'iov_size' must be <= */
00789 
00790 NSPR_API(PRInt32) PR_Writev(
00791     PRFileDesc *fd, const PRIOVec *iov, PRInt32 iov_size,
00792     PRIntervalTime timeout);
00793 
00794 /*
00795  ***************************************************************************
00796  * FUNCTION: PR_Delete
00797  * DESCRIPTION:
00798  *     Delete a file from the filesystem. The operation may fail if the
00799  *     file is open.
00800  * INPUTS:
00801  *     const char *name
00802  *         Path name of the file to be deleted.
00803  * OUTPUTS:
00804  *     None.
00805  * RETURN: PRStatus
00806  *     The function returns PR_SUCCESS if the file is successfully
00807  *     deleted, otherwise it returns PR_FAILURE.
00808  ***************************************************************************
00809  */
00810 
00811 NSPR_API(PRStatus) PR_Delete(const char *name);
00812 
00813 /**************************************************************************/
00814 
00815 typedef enum PRFileType
00816 {
00817     PR_FILE_FILE = 1,
00818     PR_FILE_DIRECTORY = 2,
00819     PR_FILE_OTHER = 3
00820 } PRFileType;
00821 
00822 struct PRFileInfo {
00823     PRFileType type;        /* Type of file */
00824     PROffset32 size;        /* Size, in bytes, of file's contents */
00825     PRTime creationTime;    /* Creation time per definition of PRTime */
00826     PRTime modifyTime;      /* Last modification time per definition of PRTime */
00827 };
00828 
00829 struct PRFileInfo64 {
00830     PRFileType type;        /* Type of file */
00831     PROffset64 size;        /* Size, in bytes, of file's contents */
00832     PRTime creationTime;    /* Creation time per definition of PRTime */
00833     PRTime modifyTime;      /* Last modification time per definition of PRTime */
00834 };
00835 
00836 /****************************************************************************
00837  * FUNCTION: PR_GetFileInfo, PR_GetFileInfo64
00838  * DESCRIPTION:
00839  *     Get the information about the file with the given path name. This is
00840  *     applicable only to NSFileDesc describing 'file' types (see
00841  * INPUTS:
00842  *     const char *fn
00843  *         path name of the file
00844  * OUTPUTS:
00845  *     PRFileInfo *info
00846  *         Information about the given file is written into the file
00847  *         information object pointer to by 'info'.
00848  * RETURN: PRStatus
00849  *     PR_GetFileInfo returns PR_SUCCESS if file information is successfully
00850  *     obtained, otherwise it returns PR_FAILURE.
00851  ***************************************************************************
00852  */
00853 
00854 NSPR_API(PRStatus) PR_GetFileInfo(const char *fn, PRFileInfo *info);
00855 NSPR_API(PRStatus) PR_GetFileInfo64(const char *fn, PRFileInfo64 *info);
00856 
00857 #ifdef MOZ_UNICODE
00858 /*
00859  * EXPERIMENTAL: This function may be removed in a future release.
00860  */
00861 NSPR_API(PRStatus) PR_GetFileInfo64UTF16(const PRUnichar *fn, PRFileInfo64 *info);
00862 #endif /* MOZ_UNICODE */
00863 
00864 /*
00865  **************************************************************************
00866  * FUNCTION: PR_GetOpenFileInfo, PR_GetOpenFileInfo64
00867  * DESCRIPTION:
00868  *     Get information about an open file referred to by the
00869  *     given PRFileDesc object.
00870  * INPUTS:
00871  *     const PRFileDesc *fd
00872  *          A reference to a valid, open file.
00873  * OUTPUTS:
00874  *     Same as PR_GetFileInfo, PR_GetFileInfo64
00875  * RETURN: PRStatus
00876  *     PR_GetFileInfo returns PR_SUCCESS if file information is successfully
00877  *     obtained, otherwise it returns PR_FAILURE.
00878  ***************************************************************************
00879  */
00880 
00881 NSPR_API(PRStatus) PR_GetOpenFileInfo(PRFileDesc *fd, PRFileInfo *info);
00882 NSPR_API(PRStatus) PR_GetOpenFileInfo64(PRFileDesc *fd, PRFileInfo64 *info);
00883 
00884 /*
00885  **************************************************************************
00886  * FUNCTION: PR_Rename
00887  * DESCRIPTION:
00888  *     Rename a file from the old name 'from' to the new name 'to'.
00889  * INPUTS:
00890  *     const char *from
00891  *         The old name of the file to be renamed.
00892  *     const char *to
00893  *         The new name of the file.
00894  * OUTPUTS:
00895  *     None.
00896  * RETURN: PRStatus
00897  **************************************************************************
00898  */
00899 
00900 NSPR_API(PRStatus)    PR_Rename(const char *from, const char *to);
00901 
00902 /*
00903  *************************************************************************
00904  * FUNCTION: PR_Access
00905  * DESCRIPTION:
00906  *     Determine accessibility of a file.
00907  * INPUTS:
00908  *     const char *name
00909  *         path name of the file
00910  *     PRAccessHow how
00911  *         specifies which access permission to check for.
00912  *         It can be one of the following values:
00913  *             PR_ACCESS_READ_OK       Test for read permission
00914  *             PR_ACCESS_WRITE_OK      Test for write permission
00915  *             PR_ACCESS_EXISTS        Check existence of file
00916  * OUTPUTS:
00917  *     None.
00918  * RETURN: PRStatus
00919  *     PR_SUCCESS is returned if the requested access is permitted.
00920  *     Otherwise, PR_FAILURE is returned. Additional information
00921  *     regarding the reason for the failure may be retrieved from
00922  *     PR_GetError().
00923  *************************************************************************
00924  */
00925 
00926 typedef enum PRAccessHow {
00927     PR_ACCESS_EXISTS = 1,
00928     PR_ACCESS_WRITE_OK = 2,
00929     PR_ACCESS_READ_OK = 3
00930 } PRAccessHow;
00931 
00932 NSPR_API(PRStatus) PR_Access(const char *name, PRAccessHow how);
00933 
00934 /*
00935  *************************************************************************
00936  * FUNCTION: PR_Seek, PR_Seek64
00937  * DESCRIPTION:
00938  *     Moves read-write file offset
00939  * INPUTS:
00940  *     PRFileDesc *fd
00941  *         Pointer to a PRFileDesc object.
00942  *     PROffset32, PROffset64 offset
00943  *         Specifies a value, in bytes, that is used in conjunction
00944  *         with the 'whence' parameter to set the file pointer.  A
00945  *         negative value causes seeking in the reverse direction.
00946  *     PRSeekWhence whence
00947  *         Specifies how to interpret the 'offset' parameter in setting
00948  *         the file pointer associated with the 'fd' parameter.
00949  *         Values for the 'whence' parameter are:
00950  *             PR_SEEK_SET  Sets the file pointer to the value of the
00951  *                          'offset' parameter
00952  *             PR_SEEK_CUR  Sets the file pointer to its current location
00953  *                          plus the value of the offset parameter.
00954  *             PR_SEEK_END  Sets the file pointer to the size of the
00955  *                          file plus the value of the offset parameter.
00956  * OUTPUTS:
00957  *     None.
00958  * RETURN: PROffset32, PROffset64
00959  *     Upon successful completion, the resulting pointer location,
00960  *     measured in bytes from the beginning of the file, is returned.
00961  *     If the PR_Seek() function fails, the file offset remains
00962  *     unchanged, and the returned value is -1. The error code can
00963  *     then be retrieved via PR_GetError().
00964  *************************************************************************
00965  */
00966 
00967 NSPR_API(PROffset32) PR_Seek(PRFileDesc *fd, PROffset32 offset, PRSeekWhence whence);
00968 NSPR_API(PROffset64) PR_Seek64(PRFileDesc *fd, PROffset64 offset, PRSeekWhence whence);
00969 
00970 /*
00971  ************************************************************************
00972  * FUNCTION: PR_Available
00973  * DESCRIPTION:
00974  *     Determine the amount of data in bytes available for reading
00975  *     in the given file or socket.
00976  * INPUTS:
00977  *     PRFileDesc *fd
00978  *         Pointer to a PRFileDesc object that refers to a file or
00979  *         socket.
00980  * OUTPUTS:
00981  *     None
00982  * RETURN: PRInt32, PRInt64
00983  *     Upon successful completion, PR_Available returns the number of
00984  *     bytes beyond the current read pointer that is available for
00985  *     reading.  Otherwise, it returns a -1 and the reason for the
00986  *     failure can be retrieved via PR_GetError().
00987  ************************************************************************
00988  */
00989 
00990 NSPR_API(PRInt32) PR_Available(PRFileDesc *fd);
00991 NSPR_API(PRInt64) PR_Available64(PRFileDesc *fd);
00992 
00993 /*
00994  ************************************************************************
00995  * FUNCTION: PR_Sync
00996  * DESCRIPTION:
00997  *     Sync any buffered data for a fd to its backing device (disk).
00998  * INPUTS:
00999  *     PRFileDesc *fd
01000  *         Pointer to a PRFileDesc object that refers to a file or
01001  *         socket
01002  * OUTPUTS:
01003  *     None
01004  * RETURN: PRStatus
01005  *     PR_SUCCESS is returned if the requested access is permitted.
01006  *     Otherwise, PR_FAILURE is returned.
01007  ************************************************************************
01008  */
01009 
01010 NSPR_API(PRStatus)   PR_Sync(PRFileDesc *fd);
01011 
01012 /************************************************************************/
01013 
01014 struct PRDirEntry {
01015     const char *name;        /* name of entry, relative to directory name */
01016 };
01017 
01018 #ifdef MOZ_UNICODE
01019 struct PRDirEntryUTF16 {
01020     const PRUnichar *name;   /* name of entry in UTF16, relative to
01021                               * directory name */
01022 };
01023 #endif /* MOZ_UNICODE */
01024 
01025 #if !defined(NO_NSPR_10_SUPPORT)
01026 #define PR_DirName(dirEntry)       (dirEntry->name)
01027 #endif
01028 
01029 /*
01030  *************************************************************************
01031  * FUNCTION: PR_OpenDir
01032  * DESCRIPTION:
01033  *     Open the directory by the given name
01034  * INPUTS:
01035  *     const char *name
01036  *         path name of the directory to be opened
01037  * OUTPUTS:
01038  *     None
01039  * RETURN: PRDir *
01040  *     If the directory is sucessfully opened, a PRDir object is
01041  *     dynamically allocated and a pointer to it is returned.
01042  *     If the directory cannot be opened, a NULL pointer is returned.
01043  * MEMORY:
01044  *     Upon successful completion, the return value points to
01045  *     dynamically allocated memory.
01046  *************************************************************************
01047  */
01048 
01049 NSPR_API(PRDir*) PR_OpenDir(const char *name);
01050 
01051 #ifdef MOZ_UNICODE
01052 /*
01053  * EXPERIMENTAL: This function may be removed in a future release.
01054  */
01055 NSPR_API(PRDirUTF16*) PR_OpenDirUTF16(const PRUnichar *name);
01056 #endif /* MOZ_UNICODE */
01057 
01058 /*
01059  *************************************************************************
01060  * FUNCTION: PR_ReadDir
01061  * DESCRIPTION:
01062  * INPUTS:
01063  *     PRDir *dir
01064  *         pointer to a PRDir object that designates an open directory
01065  *     PRDirFlags flags
01066  *           PR_SKIP_NONE     Do not skip any files
01067  *           PR_SKIP_DOT      Skip the directory entry "." that
01068  *                            represents the current directory
01069  *           PR_SKIP_DOT_DOT  Skip the directory entry ".." that
01070  *                            represents the parent directory.
01071  *           PR_SKIP_BOTH     Skip both '.' and '..'
01072  *           PR_SKIP_HIDDEN   Skip hidden files
01073  * OUTPUTS:
01074  * RETURN: PRDirEntry*
01075  *     Returns a pointer to the next entry in the directory.  Returns
01076  *     a NULL pointer upon reaching the end of the directory or when an
01077  *     error occurs. The actual reason can be retrieved via PR_GetError().
01078  *************************************************************************
01079  */
01080 
01081 typedef enum PRDirFlags {
01082     PR_SKIP_NONE = 0x0,
01083     PR_SKIP_DOT = 0x1,
01084     PR_SKIP_DOT_DOT = 0x2,
01085     PR_SKIP_BOTH = 0x3,
01086     PR_SKIP_HIDDEN = 0x4
01087 } PRDirFlags;
01088 
01089 NSPR_API(PRDirEntry*) PR_ReadDir(PRDir *dir, PRDirFlags flags);
01090 
01091 #ifdef MOZ_UNICODE
01092 /*
01093  * EXPERIMENTAL: This function may be removed in a future release.
01094  */
01095 NSPR_API(PRDirEntryUTF16*) PR_ReadDirUTF16(PRDirUTF16 *dir, PRDirFlags flags);
01096 #endif /* MOZ_UNICODE */
01097 
01098 /*
01099  *************************************************************************
01100  * FUNCTION: PR_CloseDir
01101  * DESCRIPTION:
01102  *     Close the specified directory.
01103  * INPUTS:
01104  *     PRDir *dir
01105  *        The directory to be closed.
01106  * OUTPUTS:
01107  *     None
01108  * RETURN: PRStatus
01109  *        If successful, will return a status of PR_SUCCESS. Otherwise
01110  *        a value of PR_FAILURE. The reason for the failure may be re-
01111  *        trieved using PR_GetError().
01112  *************************************************************************
01113  */
01114 
01115 NSPR_API(PRStatus) PR_CloseDir(PRDir *dir);
01116 
01117 #ifdef MOZ_UNICODE
01118 /*
01119  * EXPERIMENTAL: This function may be removed in a future release.
01120  */
01121 NSPR_API(PRStatus) PR_CloseDirUTF16(PRDirUTF16 *dir);
01122 #endif /* MOZ_UNICODE */
01123 
01124 /*
01125  *************************************************************************
01126  * FUNCTION: PR_MkDir
01127  * DESCRIPTION:
01128  *     Create a new directory with the given name and access mode.
01129  * INPUTS:
01130  *     const char *name
01131  *        The name of the directory to be created. All the path components
01132  *        up to but not including the leaf component must already exist.
01133  *     PRIntn mode
01134  *        See 'mode' definiton in PR_Open().
01135  * OUTPUTS:
01136  *     None
01137  * RETURN: PRStatus
01138  *        If successful, will return a status of PR_SUCCESS. Otherwise
01139  *        a value of PR_FAILURE. The reason for the failure may be re-
01140  *        trieved using PR_GetError().
01141  *************************************************************************
01142  */
01143 
01144 NSPR_API(PRStatus) PR_MkDir(const char *name, PRIntn mode);
01145 
01146 /*
01147  *************************************************************************
01148  * FUNCTION: PR_MakeDir
01149  * DESCRIPTION:
01150  *     Create a new directory with the given name and access mode.
01151  *     PR_MakeDir has the same prototype as PR_MkDir but implements
01152  *     the specified access mode where possible.
01153  *************************************************************************
01154  */
01155 
01156 NSPR_API(PRStatus) PR_MakeDir(const char *name, PRIntn mode);
01157 
01158 /*
01159  *************************************************************************
01160  * FUNCTION: PR_RmDir
01161  * DESCRIPTION:
01162  *     Remove a directory by the given name.
01163  * INPUTS:
01164  *     const char *name
01165  *        The name of the directory to be removed. All the path components
01166  *        must already exist. Only the leaf component will be removed.
01167  * OUTPUTS:
01168  *     None
01169  * RETURN: PRStatus
01170  *        If successful, will return a status of PR_SUCCESS. Otherwise
01171  *        a value of PR_FAILURE. The reason for the failure may be re-
01172  *        trieved using PR_GetError().
01173  **************************************************************************
01174  */
01175 
01176 NSPR_API(PRStatus) PR_RmDir(const char *name);
01177 
01178 /*
01179  *************************************************************************
01180  * FUNCTION: PR_NewUDPSocket
01181  * DESCRIPTION:
01182  *     Create a new UDP socket.
01183  * INPUTS:
01184  *     None
01185  * OUTPUTS:
01186  *     None
01187  * RETURN: PRFileDesc*
01188  *     Upon successful completion, PR_NewUDPSocket returns a pointer
01189  *     to the PRFileDesc created for the newly opened UDP socket.
01190  *     Returns a NULL pointer if the creation of a new UDP socket failed.
01191  *
01192  **************************************************************************
01193  */
01194 
01195 NSPR_API(PRFileDesc*)    PR_NewUDPSocket(void);
01196 
01197 /*
01198  *************************************************************************
01199  * FUNCTION: PR_NewTCPSocket
01200  * DESCRIPTION:
01201  *     Create a new TCP socket.
01202  * INPUTS:
01203  *     None
01204  * OUTPUTS:
01205  *     None
01206  * RETURN: PRFileDesc*
01207  *     Upon successful completion, PR_NewTCPSocket returns a pointer
01208  *     to the PRFileDesc created for the newly opened TCP socket.
01209  *     Returns a NULL pointer if the creation of a new TCP socket failed.
01210  *
01211  **************************************************************************
01212  */
01213 
01214 NSPR_API(PRFileDesc*)    PR_NewTCPSocket(void);
01215 
01216 /*
01217  *************************************************************************
01218  * FUNCTION: PR_OpenUDPSocket
01219  * DESCRIPTION:
01220  *     Create a new UDP socket of the specified address family.
01221  * INPUTS:
01222  *     PRIntn af
01223  *       Address family
01224  * OUTPUTS:
01225  *     None
01226  * RETURN: PRFileDesc*
01227  *     Upon successful completion, PR_OpenUDPSocket returns a pointer
01228  *     to the PRFileDesc created for the newly opened UDP socket.
01229  *     Returns a NULL pointer if the creation of a new UDP socket failed.
01230  *
01231  **************************************************************************
01232  */
01233 
01234 NSPR_API(PRFileDesc*)    PR_OpenUDPSocket(PRIntn af);
01235 
01236 /*
01237  *************************************************************************
01238  * FUNCTION: PR_OpenTCPSocket
01239  * DESCRIPTION:
01240  *     Create a new TCP socket of the specified address family.
01241  * INPUTS:
01242  *     PRIntn af
01243  *       Address family
01244  * OUTPUTS:
01245  *     None
01246  * RETURN: PRFileDesc*
01247  *     Upon successful completion, PR_NewTCPSocket returns a pointer
01248  *     to the PRFileDesc created for the newly opened TCP socket.
01249  *     Returns a NULL pointer if the creation of a new TCP socket failed.
01250  *
01251  **************************************************************************
01252  */
01253 
01254 NSPR_API(PRFileDesc*)    PR_OpenTCPSocket(PRIntn af);
01255 
01256 /*
01257  *************************************************************************
01258  * FUNCTION: PR_Connect
01259  * DESCRIPTION:
01260  *     Initiate a connection on a socket.
01261  * INPUTS:
01262  *     PRFileDesc *fd
01263  *       Points to a PRFileDesc object representing a socket
01264  *     PRNetAddr *addr
01265  *       Specifies the address of the socket in its own communication
01266  *       space.
01267  *     PRIntervalTime timeout
01268  *       Time limit for completion of the connect operation.
01269  * OUTPUTS:
01270  *     None
01271  * RETURN: PRStatus
01272  *     Upon successful completion of connection initiation, PR_Connect
01273  *     returns PR_SUCCESS.  Otherwise, it returns PR_FAILURE.  Further
01274  *     failure information can be obtained by calling PR_GetError().
01275  **************************************************************************
01276  */
01277 
01278 NSPR_API(PRStatus) PR_Connect(
01279     PRFileDesc *fd, const PRNetAddr *addr, PRIntervalTime timeout);
01280 
01281 /*
01282  *************************************************************************
01283  * FUNCTION: PR_ConnectContinue
01284  * DESCRIPTION:
01285  *     Continue a nonblocking connect.  After a nonblocking connect
01286  *     is initiated with PR_Connect() (which fails with
01287  *     PR_IN_PROGRESS_ERROR), one should call PR_Poll() on the socket,
01288  *     with the in_flags PR_POLL_WRITE | PR_POLL_EXCEPT.  When
01289  *     PR_Poll() returns, one calls PR_ConnectContinue() on the
01290  *     socket to determine whether the nonblocking connect has
01291  *     completed or is still in progress.  Repeat the PR_Poll(),
01292  *     PR_ConnectContinue() sequence until the nonblocking connect
01293  *     has completed.
01294  * INPUTS:
01295  *     PRFileDesc *fd
01296  *         the file descriptor representing a socket
01297  *     PRInt16 out_flags
01298  *         the out_flags field of the poll descriptor returned by
01299  *         PR_Poll()
01300  * RETURN: PRStatus
01301  *     If the nonblocking connect has successfully completed,
01302  *     PR_ConnectContinue returns PR_SUCCESS.  If PR_ConnectContinue()
01303  *     returns PR_FAILURE, call PR_GetError():
01304  *     - PR_IN_PROGRESS_ERROR: the nonblocking connect is still in
01305  *       progress and has not completed yet.  The caller should poll
01306  *       on the file descriptor for the in_flags
01307  *       PR_POLL_WRITE|PR_POLL_EXCEPT and retry PR_ConnectContinue
01308  *       later when PR_Poll() returns.
01309  *     - Other errors: the nonblocking connect has failed with this
01310  *       error code.
01311  */
01312 
01313 NSPR_API(PRStatus)    PR_ConnectContinue(PRFileDesc *fd, PRInt16 out_flags);
01314 
01315 /*
01316  *************************************************************************
01317  * THIS FUNCTION IS DEPRECATED.  USE PR_ConnectContinue INSTEAD.
01318  *
01319  * FUNCTION: PR_GetConnectStatus
01320  * DESCRIPTION:
01321  *     Get the completion status of a nonblocking connect.  After
01322  *     a nonblocking connect is initiated with PR_Connect() (which
01323  *     fails with PR_IN_PROGRESS_ERROR), one should call PR_Poll()
01324  *     on the socket, with the in_flags PR_POLL_WRITE | PR_POLL_EXCEPT.
01325  *     When PR_Poll() returns, one calls PR_GetConnectStatus on the
01326  *     PRPollDesc structure to determine whether the nonblocking
01327  *     connect has succeeded or failed.
01328  * INPUTS:
01329  *     const PRPollDesc *pd
01330  *         Pointer to a PRPollDesc whose fd member is the socket,
01331  *         and in_flags must contain PR_POLL_WRITE and PR_POLL_EXCEPT.
01332  *         PR_Poll() should have been called and set the out_flags.
01333  * RETURN: PRStatus
01334  *     If the nonblocking connect has successfully completed,
01335  *     PR_GetConnectStatus returns PR_SUCCESS.  If PR_GetConnectStatus()
01336  *     returns PR_FAILURE, call PR_GetError():
01337  *     - PR_IN_PROGRESS_ERROR: the nonblocking connect is still in
01338  *       progress and has not completed yet.
01339  *     - Other errors: the nonblocking connect has failed with this
01340  *       error code.
01341  */
01342 
01343 NSPR_API(PRStatus)    PR_GetConnectStatus(const PRPollDesc *pd);
01344 
01345 /*
01346  *************************************************************************
01347  * FUNCTION: PR_Accept
01348  * DESCRIPTION:
01349  *     Accept a connection on a socket.
01350  * INPUTS:
01351  *     PRFileDesc *fd
01352  *       Points to a PRFileDesc object representing the rendezvous socket
01353  *       on which the caller is willing to accept new connections.
01354  *     PRIntervalTime timeout
01355  *       Time limit for completion of the accept operation.
01356  * OUTPUTS:
01357  *     PRNetAddr *addr
01358  *       Returns the address of the connecting entity in its own
01359  *       communication space. It may be NULL.
01360  * RETURN: PRFileDesc*
01361  *     Upon successful acceptance of a connection, PR_Accept
01362  *     returns a valid file descriptor. Otherwise, it returns NULL.
01363  *     Further failure information can be obtained by calling PR_GetError().
01364  **************************************************************************
01365  */
01366 
01367 NSPR_API(PRFileDesc*) PR_Accept(
01368     PRFileDesc *fd, PRNetAddr *addr, PRIntervalTime timeout);
01369 
01370 /*
01371  *************************************************************************
01372  * FUNCTION: PR_Bind
01373  * DESCRIPTION:
01374  *    Bind an address to a socket.
01375  * INPUTS:
01376  *     PRFileDesc *fd
01377  *       Points to a PRFileDesc object representing a socket.
01378  *     PRNetAddr *addr
01379  *       Specifies the address to which the socket will be bound.
01380  * OUTPUTS:
01381  *     None
01382  * RETURN: PRStatus
01383  *     Upon successful binding of an address to a socket, PR_Bind
01384  *     returns PR_SUCCESS.  Otherwise, it returns PR_FAILURE.  Further
01385  *     failure information can be obtained by calling PR_GetError().
01386  **************************************************************************
01387  */
01388 
01389 NSPR_API(PRStatus) PR_Bind(PRFileDesc *fd, const PRNetAddr *addr);
01390 
01391 /*
01392  *************************************************************************
01393  * FUNCTION: PR_Listen
01394  * DESCRIPTION:
01395  *    Listen for connections on a socket.
01396  * INPUTS:
01397  *     PRFileDesc *fd
01398  *       Points to a PRFileDesc object representing a socket that will be
01399  *       used to listen for new connections.
01400  *     PRIntn backlog
01401  *       Specifies the maximum length of the queue of pending connections.
01402  * OUTPUTS:
01403  *     None
01404  * RETURN: PRStatus
01405  *     Upon successful completion of listen request, PR_Listen
01406  *     returns PR_SUCCESS.  Otherwise, it returns PR_FAILURE.  Further
01407  *     failure information can be obtained by calling PR_GetError().
01408  **************************************************************************
01409  */
01410 
01411 NSPR_API(PRStatus) PR_Listen(PRFileDesc *fd, PRIntn backlog);
01412 
01413 /*
01414  *************************************************************************
01415  * FUNCTION: PR_Shutdown
01416  * DESCRIPTION:
01417  *    Shut down part of a full-duplex connection on a socket.
01418  * INPUTS:
01419  *     PRFileDesc *fd
01420  *       Points to a PRFileDesc object representing a connected socket.
01421  *     PRIntn how
01422  *       Specifies the kind of disallowed operations on the socket.
01423  *           PR_SHUTDOWN_RCV - Further receives will be disallowed
01424  *           PR_SHUTDOWN_SEND - Further sends will be disallowed
01425  *           PR_SHUTDOWN_BOTH - Further sends and receives will be disallowed
01426  * OUTPUTS:
01427  *     None
01428  * RETURN: PRStatus
01429  *     Upon successful completion of shutdown request, PR_Shutdown
01430  *     returns PR_SUCCESS.  Otherwise, it returns PR_FAILURE.  Further
01431  *     failure information can be obtained by calling PR_GetError().
01432  **************************************************************************
01433  */
01434 
01435 typedef enum PRShutdownHow
01436 {
01437     PR_SHUTDOWN_RCV = 0,      /* disallow further receives */
01438     PR_SHUTDOWN_SEND = 1,     /* disallow further sends */
01439     PR_SHUTDOWN_BOTH = 2      /* disallow further receives and sends */
01440 } PRShutdownHow;
01441 
01442 NSPR_API(PRStatus)    PR_Shutdown(PRFileDesc *fd, PRShutdownHow how);
01443 
01444 /*
01445  *************************************************************************
01446  * FUNCTION: PR_Recv
01447  * DESCRIPTION:
01448  *    Receive a specified number of bytes from a connected socket.
01449  *     The operation will block until some positive number of bytes are 
01450  *     transferred, a time out has occurred, or there is an error. 
01451  *     No more than 'amount' bytes will be transferred.
01452  * INPUTS:
01453  *     PRFileDesc *fd
01454  *       points to a PRFileDesc object representing a socket.
01455  *     void *buf
01456  *       pointer to a buffer to hold the data received.
01457  *     PRInt32 amount
01458  *       the size of 'buf' (in bytes)
01459  *     PRIntn flags
01460  *       must be zero or PR_MSG_PEEK.
01461  *     PRIntervalTime timeout
01462  *       Time limit for completion of the receive operation.
01463  * OUTPUTS:
01464  *     None
01465  * RETURN: PRInt32
01466  *         a positive number indicates the number of bytes actually received.
01467  *         0 means the network connection is closed.
01468  *         -1 indicates a failure. The reason for the failure is obtained
01469  *         by calling PR_GetError().
01470  **************************************************************************
01471  */
01472 
01473 #define PR_MSG_PEEK 0x2
01474 
01475 NSPR_API(PRInt32)    PR_Recv(PRFileDesc *fd, void *buf, PRInt32 amount,
01476                 PRIntn flags, PRIntervalTime timeout);
01477 
01478 /*
01479  *************************************************************************
01480  * FUNCTION: PR_Send
01481  * DESCRIPTION:
01482  *    Send a specified number of bytes from a connected socket.
01483  *     The operation will block until all bytes are 
01484  *     processed, a time out has occurred, or there is an error. 
01485  * INPUTS:
01486  *     PRFileDesc *fd
01487  *       points to a PRFileDesc object representing a socket.
01488  *     void *buf
01489  *       pointer to a buffer from where the data is sent.
01490  *     PRInt32 amount
01491  *       the size of 'buf' (in bytes)
01492  *     PRIntn flags
01493  *        (OBSOLETE - must always be zero)
01494  *     PRIntervalTime timeout
01495  *       Time limit for completion of the send operation.
01496  * OUTPUTS:
01497  *     None
01498  * RETURN: PRInt32
01499  *     A positive number indicates the number of bytes successfully processed.
01500  *     This number must always equal 'amount'. A -1 is an indication that the
01501  *     operation failed. The reason for the failure is obtained by calling
01502  *     PR_GetError().
01503  **************************************************************************
01504  */
01505 
01506 NSPR_API(PRInt32)    PR_Send(PRFileDesc *fd, const void *buf, PRInt32 amount,
01507                                 PRIntn flags, PRIntervalTime timeout);
01508 
01509 /*
01510  *************************************************************************
01511  * FUNCTION: PR_RecvFrom
01512  * DESCRIPTION:
01513  *     Receive up to a specified number of bytes from socket which may
01514  *     or may not be connected.
01515  *     The operation will block until one or more bytes are 
01516  *     transferred, a time out has occurred, or there is an error. 
01517  *     No more than 'amount' bytes will be transferred.
01518  * INPUTS:
01519  *     PRFileDesc *fd
01520  *       points to a PRFileDesc object representing a socket.
01521  *     void *buf
01522  *       pointer to a buffer to hold the data received.
01523  *     PRInt32 amount
01524  *       the size of 'buf' (in bytes)
01525  *     PRIntn flags
01526  *        (OBSOLETE - must always be zero)
01527  *     PRNetAddr *addr
01528  *       Specifies the address of the sending peer. It may be NULL.
01529  *     PRIntervalTime timeout
01530  *       Time limit for completion of the receive operation.
01531  * OUTPUTS:
01532  *     None
01533  * RETURN: PRInt32
01534  *         a positive number indicates the number of bytes actually received.
01535  *         0 means the network connection is closed.
01536  *         -1 indicates a failure. The reason for the failure is obtained
01537  *         by calling PR_GetError().
01538  **************************************************************************
01539  */
01540 
01541 NSPR_API(PRInt32) PR_RecvFrom(
01542     PRFileDesc *fd, void *buf, PRInt32 amount, PRIntn flags,
01543     PRNetAddr *addr, PRIntervalTime timeout);
01544 
01545 /*
01546  *************************************************************************
01547  * FUNCTION: PR_SendTo
01548  * DESCRIPTION:
01549  *    Send a specified number of bytes from an unconnected socket.
01550  *    The operation will block until all bytes are 
01551  *    sent, a time out has occurred, or there is an error. 
01552  * INPUTS:
01553  *     PRFileDesc *fd
01554  *       points to a PRFileDesc object representing an unconnected socket.
01555  *     void *buf
01556  *       pointer to a buffer from where the data is sent.
01557  *     PRInt32 amount
01558  *       the size of 'buf' (in bytes)
01559  *     PRIntn flags
01560  *        (OBSOLETE - must always be zero)
01561  *     PRNetAddr *addr
01562  *       Specifies the address of the peer.
01563 .*     PRIntervalTime timeout
01564  *       Time limit for completion of the send operation.
01565  * OUTPUTS:
01566  *     None
01567  * RETURN: PRInt32
01568  *     A positive number indicates the number of bytes successfully sent.
01569  *     -1 indicates a failure. The reason for the failure is obtained
01570  *     by calling PR_GetError().
01571  **************************************************************************
01572  */
01573 
01574 NSPR_API(PRInt32) PR_SendTo(
01575     PRFileDesc *fd, const void *buf, PRInt32 amount, PRIntn flags,
01576     const PRNetAddr *addr, PRIntervalTime timeout);
01577 
01578 /*
01579 *************************************************************************
01580 ** FUNCTION: PR_TransmitFile
01581 ** DESCRIPTION:
01582 **    Transmitfile sends a complete file (sourceFile) across a socket 
01583 **    (networkSocket).  If headers is non-NULL, the headers will be sent across
01584 **    the socket prior to sending the file.
01585 ** 
01586 **    Optionally, the PR_TRANSMITFILE_CLOSE_SOCKET flag may be passed to
01587 **    transmitfile.  This flag specifies that transmitfile should close the
01588 **    socket after sending the data.
01589 **
01590 ** INPUTS:
01591 **    PRFileDesc *networkSocket
01592 **        The socket to send data over
01593 **    PRFileDesc *sourceFile
01594 **        The file to send
01595 **    const void *headers
01596 **        A pointer to headers to be sent before sending data
01597 **    PRInt32       hlen
01598 **        length of header buffers in bytes.
01599 **    PRTransmitFileFlags       flags
01600 **        If the flags indicate that the connection should be closed,
01601 **        it will be done immediately after transferring the file, unless
01602 **        the operation is unsuccessful. 
01603 .*     PRIntervalTime timeout
01604  *        Time limit for completion of the transmit operation.
01605 **
01606 ** RETURNS:
01607 **    Returns the number of bytes written or -1 if the operation failed.
01608 **    If an error occurs while sending the file, the PR_TRANSMITFILE_CLOSE_
01609 **    SOCKET flag is ignored. The reason for the failure is obtained
01610 **    by calling PR_GetError().
01611 **************************************************************************
01612 */
01613 
01614 NSPR_API(PRInt32) PR_TransmitFile(
01615     PRFileDesc *networkSocket, PRFileDesc *sourceFile,
01616     const void *headers, PRInt32 hlen, PRTransmitFileFlags flags,
01617     PRIntervalTime timeout);
01618 
01619 /*
01620 *************************************************************************
01621 ** FUNCTION: PR_SendFile
01622 ** DESCRIPTION:
01623 **    PR_SendFile sends data from a file (sendData->fd) across a socket 
01624 **    (networkSocket).  If specified, a header and/or trailer buffer are sent
01625 **       before and after the file, respectively. The file offset, number of bytes
01626 **       of file data to send, the header and trailer buffers are specified in the
01627 **       sendData argument.
01628 ** 
01629 **    Optionally, if the PR_TRANSMITFILE_CLOSE_SOCKET flag is passed, the
01630 **    socket is closed after successfully sending the data.
01631 **
01632 ** INPUTS:
01633 **    PRFileDesc *networkSocket
01634 **        The socket to send data over
01635 **    PRSendFileData *sendData
01636 **        Contains the FD, file offset and length, header and trailer
01637 **              buffer specifications.
01638 **    PRTransmitFileFlags       flags
01639 **        If the flags indicate that the connection should be closed,
01640 **        it will be done immediately after transferring the file, unless
01641 **        the operation is unsuccessful. 
01642 .*     PRIntervalTime timeout
01643  *        Time limit for completion of the send operation.
01644 **
01645 ** RETURNS:
01646 **    Returns the number of bytes written or -1 if the operation failed.
01647 **    If an error occurs while sending the file, the PR_TRANSMITFILE_CLOSE_
01648 **    SOCKET flag is ignored. The reason for the failure is obtained
01649 **    by calling PR_GetError().
01650 **************************************************************************
01651 */
01652 
01653 struct PRSendFileData {
01654        PRFileDesc    *fd;                 /* file to send                                                */
01655        PRUint32      file_offset;  /* file offset                                                 */
01656        PRSize        file_nbytes;  /* number of bytes of file data to send   */
01657                                                         /* if 0, send data from file_offset to    */
01658                                                         /* end-of-file.                                                */
01659        const void    *header;             /* header buffer                                        */
01660        PRInt32              hlen;                /* header len                                           */
01661        const void    *trailer;            /* trailer buffer                                       */
01662        PRInt32              tlen;                /* trailer len                                                 */
01663 };
01664 
01665 
01666 NSPR_API(PRInt32) PR_SendFile(
01667     PRFileDesc *networkSocket, PRSendFileData *sendData,
01668        PRTransmitFileFlags flags, PRIntervalTime timeout);
01669 
01670 /*
01671 *************************************************************************
01672 ** FUNCTION: PR_AcceptRead
01673 ** DESCRIPTION:
01674 **    AcceptRead accepts a new connection, returns the newly created
01675 **    socket's descriptor and also returns the connecting peer's address.
01676 **    AcceptRead, as its name suggests, also receives the first block of data 
01677 **    sent by the peer.
01678 **
01679 ** INPUTS:
01680 **    PRFileDesc *listenSock
01681 **        A socket descriptor that has been called with the PR_Listen() 
01682 **        function, also known as the rendezvous socket.
01683 **    void *buf
01684 **        A pointer to a buffer to receive data sent by the client.  This 
01685 **        buffer must be large enough to receive <amount> bytes of data
01686 **        and two PRNetAddr structures, plus an extra 32 bytes. See:
01687 **        PR_ACCEPT_READ_BUF_OVERHEAD.
01688 **    PRInt32 amount
01689 **        The number of bytes of client data to receive.  Does not include
01690 **        the size of the PRNetAddr structures.  If 0, no data will be read
01691 **        from the client.
01692 **    PRIntervalTime timeout
01693 **        The timeout interval only applies to the read portion of the 
01694 **        operation.  PR_AcceptRead will block indefinitely until the 
01695 **        connection is accepted; the read will timeout after the timeout 
01696 **        interval elapses.
01697 ** OUTPUTS:
01698 **    PRFileDesc **acceptedSock
01699 **        The file descriptor for the newly connected socket.  This parameter
01700 **        will only be valid if the function return does not indicate failure.
01701 **    PRNetAddr  **peerAddr,
01702 **        The address of the remote socket.  This parameter will only be
01703 **        valid if the function return does not indicate failure.  The
01704 **        returned address is not guaranteed to be properly aligned.
01705 ** 
01706 ** RETURNS:
01707 **     The number of bytes read from the client or -1 on failure.  The reason 
01708 **     for the failure is obtained by calling PR_GetError().
01709 **************************************************************************
01710 **/       
01711 /* define buffer overhead constant. Add this value to the user's 
01712 ** data length when allocating a buffer to accept data.
01713 **    Example:
01714 **    #define USER_DATA_SIZE 10
01715 **    char buf[USER_DATA_SIZE + PR_ACCEPT_READ_BUF_OVERHEAD];
01716 **    bytesRead = PR_AcceptRead( s, fd, &a, &p, USER_DATA_SIZE, ...);
01717 */
01718 #define PR_ACCEPT_READ_BUF_OVERHEAD (32+(2*sizeof(PRNetAddr)))
01719 
01720 NSPR_API(PRInt32) PR_AcceptRead(
01721     PRFileDesc *listenSock, PRFileDesc **acceptedSock,
01722     PRNetAddr **peerAddr, void *buf, PRInt32 amount, PRIntervalTime timeout);
01723 
01724 /*
01725 *************************************************************************
01726 ** FUNCTION: PR_NewTCPSocketPair
01727 ** DESCRIPTION:
01728 **    Create a new TCP socket pair. The returned descriptors can be used
01729 **    interchangeably; they are interconnected full-duplex descriptors: data
01730 **    written to one can be read from the other and vice-versa.
01731 **
01732 ** INPUTS:
01733 **    None
01734 ** OUTPUTS:
01735 **    PRFileDesc *fds[2]
01736 **        The file descriptor pair for the newly created TCP sockets.
01737 ** RETURN: PRStatus
01738 **     Upon successful completion of TCP socket pair, PR_NewTCPSocketPair 
01739 **     returns PR_SUCCESS.  Otherwise, it returns PR_FAILURE.  Further
01740 **     failure information can be obtained by calling PR_GetError().
01741 ** XXX can we implement this on windoze and mac?
01742 **************************************************************************
01743 **/
01744 NSPR_API(PRStatus) PR_NewTCPSocketPair(PRFileDesc *fds[2]);
01745 
01746 /*
01747 *************************************************************************
01748 ** FUNCTION: PR_GetSockName
01749 ** DESCRIPTION:
01750 **    Get socket name.  Return the network address for this socket.
01751 **
01752 ** INPUTS:
01753 **     PRFileDesc *fd
01754 **       Points to a PRFileDesc object representing the socket.
01755 ** OUTPUTS:
01756 **     PRNetAddr *addr
01757 **       Returns the address of the socket in its own communication space.
01758 ** RETURN: PRStatus
01759 **     Upon successful completion, PR_GetSockName returns PR_SUCCESS.  
01760 **     Otherwise, it returns PR_FAILURE.  Further failure information can 
01761 **     be obtained by calling PR_GetError().
01762 **************************************************************************
01763 **/
01764 NSPR_API(PRStatus)   PR_GetSockName(PRFileDesc *fd, PRNetAddr *addr);
01765 
01766 /*
01767 *************************************************************************
01768 ** FUNCTION: PR_GetPeerName
01769 ** DESCRIPTION:
01770 **    Get name of the connected peer.  Return the network address for the 
01771 **    connected peer socket.
01772 **
01773 ** INPUTS:
01774 **     PRFileDesc *fd
01775 **       Points to a PRFileDesc object representing the connected peer.
01776 ** OUTPUTS:
01777 **     PRNetAddr *addr
01778 **       Returns the address of the connected peer in its own communication
01779 **       space.
01780 ** RETURN: PRStatus
01781 **     Upon successful completion, PR_GetPeerName returns PR_SUCCESS.  
01782 **     Otherwise, it returns PR_FAILURE.  Further failure information can 
01783 **     be obtained by calling PR_GetError().
01784 **************************************************************************
01785 **/
01786 NSPR_API(PRStatus)   PR_GetPeerName(PRFileDesc *fd, PRNetAddr *addr);
01787 
01788 NSPR_API(PRStatus)   PR_GetSocketOption(
01789     PRFileDesc *fd, PRSocketOptionData *data);
01790 
01791 NSPR_API(PRStatus)   PR_SetSocketOption(
01792     PRFileDesc *fd, const PRSocketOptionData *data);
01793 
01794 /*
01795  *********************************************************************
01796  *
01797  * File descriptor inheritance
01798  *
01799  *********************************************************************
01800  */
01801 
01802 /*
01803  ************************************************************************
01804  * FUNCTION: PR_SetFDInheritable
01805  * DESCRIPTION:
01806  *    Set the inheritance attribute of a file descriptor.
01807  *
01808  * INPUTS:
01809  *     PRFileDesc *fd
01810  *       Points to a PRFileDesc object.
01811  *     PRBool inheritable
01812  *       If PR_TRUE, the file descriptor fd is set to be inheritable
01813  *       by a child process.  If PR_FALSE, the file descriptor is set
01814  *       to be not inheritable by a child process.
01815  * RETURN: PRStatus
01816  *     Upon successful completion, PR_SetFDInheritable returns PR_SUCCESS.  
01817  *     Otherwise, it returns PR_FAILURE.  Further failure information can 
01818  *     be obtained by calling PR_GetError().
01819  *************************************************************************
01820  */
01821 NSPR_API(PRStatus) PR_SetFDInheritable(
01822     PRFileDesc *fd,
01823     PRBool inheritable);
01824 
01825 /*
01826  ************************************************************************
01827  * FUNCTION: PR_GetInheritedFD
01828  * DESCRIPTION:
01829  *    Get an inherited file descriptor with the specified name.
01830  *
01831  * INPUTS:
01832  *     const char *name
01833  *       The name of the inherited file descriptor.
01834  * RETURN: PRFileDesc *
01835  *     Upon successful completion, PR_GetInheritedFD returns the
01836  *     inherited file descriptor with the specified name.  Otherwise,  
01837  *     it returns NULL.  Further failure information can be obtained
01838  *     by calling PR_GetError().
01839  *************************************************************************
01840  */
01841 NSPR_API(PRFileDesc *) PR_GetInheritedFD(const char *name);
01842 
01843 /*
01844  *********************************************************************
01845  *
01846  * Memory-mapped files
01847  *
01848  *********************************************************************
01849  */
01850 
01851 typedef struct PRFileMap PRFileMap;
01852 
01853 /*
01854  * protection options for read and write accesses of a file mapping
01855  */
01856 typedef enum PRFileMapProtect {
01857     PR_PROT_READONLY,     /* read only */
01858     PR_PROT_READWRITE,    /* readable, and write is shared */
01859     PR_PROT_WRITECOPY     /* readable, and write is private (copy-on-write) */
01860 } PRFileMapProtect;
01861 
01862 NSPR_API(PRFileMap *) PR_CreateFileMap(
01863     PRFileDesc *fd,
01864     PRInt64 size,
01865     PRFileMapProtect prot);
01866 
01867 /*
01868  * return the alignment (in bytes) of the offset argument to PR_MemMap
01869  */
01870 NSPR_API(PRInt32) PR_GetMemMapAlignment(void);
01871 
01872 NSPR_API(void *) PR_MemMap(
01873     PRFileMap *fmap,
01874     PROffset64 offset,  /* must be aligned and sized according to the
01875                          * return value of PR_GetMemMapAlignment() */
01876     PRUint32 len);
01877 
01878 NSPR_API(PRStatus) PR_MemUnmap(void *addr, PRUint32 len);
01879 
01880 NSPR_API(PRStatus) PR_CloseFileMap(PRFileMap *fmap);
01881 
01882 /*
01883  ******************************************************************
01884  *
01885  * Interprocess communication
01886  *
01887  ******************************************************************
01888  */
01889 
01890 /*
01891  * Creates an anonymous pipe and returns file descriptors for the
01892  * read and write ends of the pipe.
01893  */
01894 
01895 NSPR_API(PRStatus) PR_CreatePipe(
01896     PRFileDesc **readPipe,
01897     PRFileDesc **writePipe
01898 );
01899 
01900 /************************************************************************/
01901 /************** The following definitions are for poll ******************/
01902 /************************************************************************/
01903 
01904 struct PRPollDesc {
01905     PRFileDesc* fd;
01906     PRInt16 in_flags;
01907     PRInt16 out_flags;
01908 };
01909 
01910 /*
01911 ** Bit values for PRPollDesc.in_flags or PRPollDesc.out_flags. Binary-or
01912 ** these together to produce the desired poll request.
01913 */
01914 
01915 #if defined(_PR_POLL_BACKCOMPAT)
01916 
01917 #include <poll.h>
01918 #define PR_POLL_READ    POLLIN
01919 #define PR_POLL_WRITE   POLLOUT
01920 #define PR_POLL_EXCEPT  POLLPRI
01921 #define PR_POLL_ERR     POLLERR     /* only in out_flags */
01922 #define PR_POLL_NVAL    POLLNVAL    /* only in out_flags when fd is bad */
01923 #define PR_POLL_HUP     POLLHUP     /* only in out_flags */
01924 
01925 #else  /* _PR_POLL_BACKCOMPAT */
01926 
01927 #define PR_POLL_READ    0x1
01928 #define PR_POLL_WRITE   0x2
01929 #define PR_POLL_EXCEPT  0x4
01930 #define PR_POLL_ERR     0x8         /* only in out_flags */
01931 #define PR_POLL_NVAL    0x10        /* only in out_flags when fd is bad */
01932 #define PR_POLL_HUP     0x20        /* only in out_flags */
01933 
01934 #endif  /* _PR_POLL_BACKCOMPAT */
01935 
01936 /*
01937 *************************************************************************
01938 ** FUNCTION:    PR_Poll
01939 ** DESCRIPTION:
01940 **
01941 ** The call returns as soon as I/O is ready on one or more of the underlying
01942 ** socket objects. A count of the number of ready descriptors is
01943 ** returned unless a timeout occurs in which case zero is returned.
01944 **
01945 ** PRPollDesc.fd should be set to a pointer to a PRFileDesc object
01946 ** representing a socket. This field can be set to NULL to indicate to
01947 ** PR_Poll that this PRFileDesc object should be ignored.
01948 ** PRPollDesc.in_flags should be set to the desired request
01949 ** (read/write/except or some combination). Upon successful return from
01950 ** this call PRPollDesc.out_flags will be set to indicate what kind of
01951 ** i/o can be performed on the respective descriptor. PR_Poll() uses the
01952 ** out_flags fields as scratch variables during the call. If PR_Poll()
01953 ** returns 0 or -1, the out_flags fields do not contain meaningful values
01954 ** and must not be used.
01955 **
01956 ** INPUTS:
01957 **      PRPollDesc *pds         A pointer to an array of PRPollDesc
01958 **
01959 **      PRIntn npds             The number of elements in the array
01960 **                              If this argument is zero PR_Poll is
01961 **                              equivalent to a PR_Sleep(timeout).
01962 **
01963 **      PRIntervalTime timeout  Amount of time the call will block waiting
01964 **                              for I/O to become ready. If this time expires
01965 **                              w/o any I/O becoming ready, the result will
01966 **                              be zero.
01967 **
01968 ** OUTPUTS:    None
01969 ** RETURN:
01970 **      PRInt32                 Number of PRPollDesc's with events or zero
01971 **                              if the function timed out or -1 on failure.
01972 **                              The reason for the failure is obtained by
01973 **                              calling PR_GetError().
01974 **************************************************************************
01975 */
01976 NSPR_API(PRInt32) PR_Poll(
01977     PRPollDesc *pds, PRIntn npds, PRIntervalTime timeout);
01978 
01979 /*
01980 **************************************************************************
01981 **
01982 ** Pollable events
01983 **
01984 ** A pollable event is a special kind of file descriptor.
01985 ** The only I/O operation you can perform on a pollable event
01986 ** is to poll it with the PR_POLL_READ flag.  You can't
01987 ** read from or write to a pollable event.
01988 **
01989 ** The purpose of a pollable event is to combine event waiting
01990 ** with I/O waiting in a single PR_Poll call.  Pollable events
01991 ** are implemented using a pipe or a pair of TCP sockets
01992 ** connected via the loopback address, therefore setting and
01993 ** waiting for pollable events are expensive operating system
01994 ** calls.  Do not use pollable events for general thread
01995 ** synchronization. Use condition variables instead.
01996 **
01997 ** A pollable event has two states: set and unset.  Events
01998 ** are not queued, so there is no notion of an event count.
01999 ** A pollable event is either set or unset.
02000 **
02001 ** A new pollable event is created by a PR_NewPollableEvent
02002 ** call and is initially in the unset state.
02003 **
02004 ** PR_WaitForPollableEvent blocks the calling thread until
02005 ** the pollable event is set, and then it atomically unsets
02006 ** the pollable event before it returns.
02007 **
02008 ** To set a pollable event, call PR_SetPollableEvent.
02009 **
02010 ** One can call PR_Poll with the PR_POLL_READ flag on a pollable
02011 ** event.  When the pollable event is set, PR_Poll returns with
02012 ** the PR_POLL_READ flag set in the out_flags.
02013 **
02014 ** To close a pollable event, call PR_DestroyPollableEvent
02015 ** (not PR_Close).
02016 **
02017 **************************************************************************
02018 */
02019 
02020 NSPR_API(PRFileDesc *) PR_NewPollableEvent(void);
02021 
02022 NSPR_API(PRStatus) PR_DestroyPollableEvent(PRFileDesc *event);
02023 
02024 NSPR_API(PRStatus) PR_SetPollableEvent(PRFileDesc *event);
02025 
02026 NSPR_API(PRStatus) PR_WaitForPollableEvent(PRFileDesc *event);
02027 
02028 PR_END_EXTERN_C
02029 
02030 #endif /* prio_h___ */