home *** CD-ROM | disk | FTP | other *** search
/ Tools / WinSN5.0Ver.iso / NETSCAP.50 / WIN1998.ZIP / ns / nsprpub / pr / include / prio.h < prev    next >
Encoding:
C/C++ Source or Header  |  1998-04-08  |  61.4 KB  |  1,583 lines
  1. /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
  2. /*
  3.  * The contents of this file are subject to the Netscape Public License
  4.  * Version 1.0 (the "NPL"); you may not use this file except in
  5.  * compliance with the NPL.  You may obtain a copy of the NPL at
  6.  * http://www.mozilla.org/NPL/
  7.  * 
  8.  * Software distributed under the NPL is distributed on an "AS IS" basis,
  9.  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the NPL
  10.  * for the specific language governing rights and limitations under the
  11.  * NPL.
  12.  * 
  13.  * The Initial Developer of this code under the NPL is Netscape
  14.  * Communications Corporation.  Portions created by Netscape are
  15.  * Copyright (C) 1998 Netscape Communications Corporation.  All Rights
  16.  * Reserved.
  17.  */
  18.  
  19. /*
  20.  * File:     prio.h
  21.  *
  22.  * Description:    PR i/o related stuff, such as file system access, file
  23.  *         i/o, socket i/o, etc.
  24.  */
  25.  
  26. #ifndef prio_h___
  27. #define prio_h___
  28.  
  29. #include "prlong.h"
  30. #include "prtime.h"
  31. #include "prinrval.h"
  32. #include "prinet.h"
  33.  
  34. PR_BEGIN_EXTERN_C
  35.  
  36. /* Typedefs */
  37. typedef struct PRDir            PRDir;
  38. typedef struct PRDirEntry       PRDirEntry;
  39. typedef struct PRFileDesc       PRFileDesc;
  40. typedef struct PRFileInfo       PRFileInfo;
  41. typedef struct PRFileInfo64     PRFileInfo64;
  42. typedef union  PRNetAddr        PRNetAddr;
  43. typedef struct PRIOMethods      PRIOMethods;
  44. typedef struct PRPollDesc       PRPollDesc;
  45. typedef struct PRFilePrivate    PRFilePrivate;
  46.  
  47. /*
  48. ***************************************************************************
  49. ** The file descriptor.
  50. ** This is the primary structure to represent any active open socket,
  51. ** whether it be a normal file or a network connection. Such objects
  52. ** are stackable (or layerable). Each layer may have its own set of
  53. ** method pointers and context private to that layer. All each layer
  54. ** knows about its neighbors is how to get to their method table.
  55. ***************************************************************************
  56. */
  57.  
  58. typedef PRIntn PRDescIdentity;          /* see: Layering file descriptors */
  59.  
  60. struct PRFileDesc {
  61.     const PRIOMethods *methods;         /* the I/O methods table */
  62.     PRFilePrivate *secret;              /* layer dependent data */
  63.     PRFileDesc *lower, *higher;         /* pointers to adjacent layers */
  64.     void (PR_CALLBACK *dtor)(PRFileDesc *fd);
  65.                                         /* A destructor function for layer */
  66.     PRDescIdentity identity;            /* Identity of this particular layer  */
  67. };
  68.  
  69. /*
  70. ***************************************************************************
  71. ** PRTransmitFileFlags
  72. **
  73. ** Flags for PR_TransmitFile.  Pass PR_TRANSMITFILE_CLOSE_SOCKET to
  74. ** PR_TransmitFile if the connection should be closed after the file
  75. ** is transmitted.
  76. ***************************************************************************
  77. */
  78. typedef enum PRTransmitFileFlags {
  79.     PR_TRANSMITFILE_KEEP_OPEN = 0,    /* socket is left open after file
  80.                                        * is transmitted. */
  81.     PR_TRANSMITFILE_CLOSE_SOCKET = 1  /* socket is closed after file
  82.                                        * is transmitted. */
  83. } PRTransmitFileFlags;
  84.  
  85. /*
  86. **************************************************************************
  87. ** A network address
  88. **
  89. ** Only Internet Protocol (IPv4 and IPv6) addresses are supported.
  90. ** The address family must always represent IPv4 (AF_INET, probably == 2)
  91. ** or IPv6 (AF_INET6).
  92. **************************************************************************
  93. *************************************************************************/
  94. #if defined(_PR_INET6)
  95.  
  96. #if !defined(AF_INET6)
  97. #error "AF_INET6 is not defined"
  98. #endif
  99.  
  100. typedef struct in6_addr PRIPv6Addr;
  101.  
  102. #define PR_NETADDR_SIZE(_addr) PR_NetAddrSize(_addr)
  103.  
  104. #else
  105.  
  106. #define PR_NETADDR_SIZE(_addr) sizeof(PRNetAddr)
  107.  
  108. #endif /* defined(_PR_INET6) */
  109.  
  110. union PRNetAddr {
  111.     struct {
  112.         PRUint16 family;                /* address family (0x00ff maskable) */
  113.         char data[14];                  /* raw address data */
  114.     } raw;
  115.     struct {
  116.         PRUint16 family;                /* address family (AF_INET) */
  117.         PRUint16 port;                  /* port number */
  118.         PRUint32 ip;                    /* The actual 32 bits of address */
  119.         char pad[8];
  120.     } inet;
  121. #if defined(_PR_INET6)
  122.     struct {
  123.         PRUint16 family;                /* address family (AF_INET | AF_INET6) */
  124.         PRUint16 port;                  /* port number */
  125.         PRUint32 flowinfo;              /* routing information */
  126.         PRIPv6Addr ip;                  /* the actual 128 bits of address */
  127.     } ipv6;
  128. #endif /* defined(_PR_INET6) */
  129. };
  130.  
  131. /*
  132. ***************************************************************************
  133. ** PRSockOption
  134. **
  135. ** The file descriptors can have predefined options set after they file
  136. ** descriptor is created to change their behavior. Only the options in
  137. ** the following enumeration are supported.
  138. ***************************************************************************
  139. */
  140. typedef enum PRSockOption
  141. {
  142.     PR_SockOpt_Nonblocking,     /* nonblocking io */
  143.     PR_SockOpt_Linger,          /* linger on close if data present */
  144.     PR_SockOpt_Reuseaddr,       /* allow local address reuse */
  145.     PR_SockOpt_Keepalive,       /* keep connections alive */
  146.     PR_SockOpt_RecvBufferSize,  /* send buffer size */
  147.     PR_SockOpt_SendBufferSize,  /* receive buffer size */
  148.  
  149.     PR_SockOpt_IpTimeToLive,    /* time to live */
  150.     PR_SockOpt_IpTypeOfService, /* type of service and precedence */
  151.  
  152.     PR_SockOpt_AddMember,       /* add an IP group membership */
  153.     PR_SockOpt_DropMember,      /* drop an IP group membership */
  154.     PR_SockOpt_McastInterface,  /* multicast interface address */
  155.     PR_SockOpt_McastTimeToLive, /* multicast timetolive */
  156.     PR_SockOpt_McastLoopback,   /* multicast loopback */
  157.  
  158.     PR_SockOpt_NoDelay,         /* don't delay send to coalesce packets */
  159.     PR_SockOpt_MaxSegment,      /* maximum segment size */
  160.     PR_SockOpt_Last
  161. } PRSockOption;
  162.  
  163. typedef struct PRLinger {
  164.     PRBool polarity;            /* Polarity of the option's setting */
  165.     PRIntervalTime linger;        /* Time to linger before closing */
  166. } PRLinger;
  167.  
  168. typedef struct PRMcastRequest {
  169.     PRNetAddr mcaddr;            /* IP multicast address of group */
  170.     PRNetAddr ifaddr;            /* local IP address of interface */
  171. } PRMcastRequest;
  172.  
  173. typedef struct PRSocketOptionData
  174. {
  175.     PRSockOption option;
  176.     union
  177.     {
  178.         PRUintn ip_ttl;             /* IP time to live */
  179.         PRUintn mcast_ttl;          /* IP multicast time to live */
  180.         PRUintn tos;                /* IP type of service and precedence */
  181.         PRBool non_blocking;        /* Non-blocking (network) I/O */
  182.         PRBool reuse_addr;          /* Allow local address reuse */
  183.         PRBool keep_alive;          /* Keep connections alive */
  184.         PRBool mcast_loopback;      /* IP multicast loopback */
  185.         PRBool no_delay;            /* Don't delay send to coalesce packets */
  186.         PRSize max_segment;         /* Maximum segment size */
  187.         PRSize recv_buffer_size;    /* Receive buffer size */
  188.         PRSize send_buffer_size;    /* Send buffer size */
  189.         PRLinger linger;            /* Time to linger on close if data present */
  190.         PRMcastRequest add_member;  /* add an IP group membership */
  191.         PRMcastRequest drop_member; /* Drop an IP group membership */
  192.         PRNetAddr mcast_if;         /* multicast interface address */
  193.     } value;
  194. } PRSocketOptionData;
  195.  
  196. /*
  197. ***************************************************************************
  198. ** PRIOVec
  199. **
  200. ** The I/O vector is used by the write vector method to describe the areas
  201. ** that are affected by the ouput operation.
  202. ***************************************************************************
  203. */
  204. typedef struct PRIOVec {
  205.     char *iov_base;
  206.     int iov_len;
  207. } PRIOVec;
  208.  
  209. /*
  210. ***************************************************************************
  211. ** Discover what type of socket is being described by the file descriptor.
  212. ***************************************************************************
  213. */
  214. typedef enum PRDescType
  215. {
  216.     PR_DESC_FILE = 1,
  217.     PR_DESC_SOCKET_TCP = 2,
  218.     PR_DESC_SOCKET_UDP = 3,
  219.     PR_DESC_LAYERED = 4
  220. } PRDescType;
  221.  
  222. typedef enum PRSeekWhence {
  223.     PR_SEEK_SET = 0,
  224.     PR_SEEK_CUR = 1,
  225.     PR_SEEK_END = 2
  226. } PRSeekWhence;
  227.  
  228. PR_EXTERN(PRDescType) PR_GetDescType(PRFileDesc *file);
  229.  
  230. /*
  231. ***************************************************************************
  232. ** PRIOMethods
  233. **
  234. ** The I/O methods table provides procedural access to the functions of
  235. ** the file descriptor. It is the responsibility of a layer implementor
  236. ** to provide suitable functions at every entry point. If a layer provides
  237. ** no functionality, it should call the next lower(higher) function of the
  238. ** same name (e.g., return fd->lower->method->close(fd->lower));
  239. **
  240. ** Not all functions are implemented for all types of files. In cases where
  241. ** that is true, the function will return a error indication with an error
  242. ** code of PR_INVALID_METHOD_ERROR.
  243. ***************************************************************************
  244. */
  245.  
  246. typedef PRStatus (PR_CALLBACK *PRCloseFN)(PRFileDesc *fd);
  247. typedef PRInt32 (PR_CALLBACK *PRReadFN)(PRFileDesc *fd, void *buf, PRInt32 amount);
  248. typedef PRInt32 (PR_CALLBACK *PRWriteFN)(PRFileDesc *fd, const void *buf, PRInt32 amount);
  249. typedef PRInt32 (PR_CALLBACK *PRAvailableFN)(PRFileDesc *fd);
  250. typedef PRInt64 (PR_CALLBACK *PRAvailable64FN)(PRFileDesc *fd);
  251. typedef PRStatus (PR_CALLBACK *PRFsyncFN)(PRFileDesc *fd);
  252. typedef PRInt32 (PR_CALLBACK *PRSeekFN)(PRFileDesc *fd, PRInt32 offset, PRSeekWhence how);
  253. typedef PRInt64 (PR_CALLBACK *PRSeek64FN)(PRFileDesc *fd, PRInt64 offset, PRSeekWhence how);
  254. typedef PRStatus (PR_CALLBACK *PRFileInfoFN)(PRFileDesc *fd, PRFileInfo *info);
  255. typedef PRStatus (PR_CALLBACK *PRFileInfo64FN)(PRFileDesc *fd, PRFileInfo64 *info);
  256. typedef PRInt32 (PR_CALLBACK *PRWritevFN)(
  257.     PRFileDesc *fd, PRIOVec *iov, PRInt32 size, PRIntervalTime timeout);
  258. typedef PRStatus (PR_CALLBACK *PRConnectFN)(
  259.     PRFileDesc *fd, const PRNetAddr *addr, PRIntervalTime timeout);
  260. typedef PRFileDesc* (PR_CALLBACK *PRAcceptFN) (
  261.     PRFileDesc *fd, PRNetAddr *addr, PRIntervalTime timeout);
  262. typedef PRStatus (PR_CALLBACK *PRBindFN)(PRFileDesc *fd, const PRNetAddr *addr);
  263. typedef PRStatus (PR_CALLBACK *PRListenFN)(PRFileDesc *fd, PRIntn backlog);
  264. typedef PRStatus (PR_CALLBACK *PRShutdownFN)(PRFileDesc *fd, PRIntn how);
  265. typedef PRInt32 (PR_CALLBACK *PRRecvFN)(
  266.     PRFileDesc *fd, void *buf, PRInt32 amount,
  267.     PRIntn flags, PRIntervalTime timeout);
  268. typedef PRInt32 (PR_CALLBACK *PRSendFN) (
  269.     PRFileDesc *fd, const void *buf, PRInt32 amount,
  270.     PRIntn flags, PRIntervalTime timeout);
  271. typedef PRInt32 (PR_CALLBACK *PRRecvfromFN)(
  272.     PRFileDesc *fd, void *buf, PRInt32 amount,
  273.     PRIntn flags, PRNetAddr *addr, PRIntervalTime timeout);
  274. typedef PRInt32 (PR_CALLBACK *PRSendtoFN)(
  275.     PRFileDesc *fd, const void *buf, PRInt32 amount,
  276.     PRIntn flags, const PRNetAddr *addr, PRIntervalTime timeout);
  277. typedef PRInt16 (PR_CALLBACK *PRPollFN)(
  278.     PRFileDesc *fd, PRInt16 how_flags);
  279. typedef PRInt32 (PR_CALLBACK *PRAcceptreadFN)(
  280.     PRFileDesc *sd, PRFileDesc **nd, PRNetAddr **raddr,
  281.     void *buf, PRInt32 amount, PRIntervalTime t);
  282. typedef PRInt32 (PR_CALLBACK *PRTransmitfileFN)(
  283.      PRFileDesc *sd, PRFileDesc *fd, const void *headers,
  284.      PRInt32 hlen, PRTransmitFileFlags flags, PRIntervalTime t);
  285. typedef PRStatus (PR_CALLBACK *PRGetsocknameFN)(PRFileDesc *fd, PRNetAddr *addr);
  286. typedef PRStatus (PR_CALLBACK *PRGetpeernameFN)(PRFileDesc *fd, PRNetAddr *addr);
  287. typedef PRStatus (PR_CALLBACK *PRGetsockoptFN)(  /* OBSOLETE */
  288.     PRFileDesc *fd, PRSockOption optname, void* optval, PRInt32 *optlen);
  289. typedef PRStatus (PR_CALLBACK *PRSetsockoptFN)(  /* OBSOLETE */
  290.     PRFileDesc *fd, PRSockOption optname, const void* optval, PRInt32 optlen);
  291. typedef PRStatus (PR_CALLBACK *PRGetsocketoptionFN)(
  292.     PRFileDesc *fd, PRSocketOptionData *data);
  293. typedef PRStatus (PR_CALLBACK *PRSetsocketoptionFN)(
  294.     PRFileDesc *fd, const PRSocketOptionData *data);
  295.  
  296. struct PRIOMethods {
  297.     PRDescType file_type;           /* Type of file represented (tos)           */
  298.     PRCloseFN close;                /* close file and destroy descriptor        */
  299.     PRReadFN read;                  /* read up to specified bytes into buffer   */
  300.     PRWriteFN write;                /* write specified bytes from buffer        */
  301.     PRAvailableFN available;        /* determine number of bytes available      */
  302.     PRAvailable64FN available64;    /*          ditto, 64 bit                   */
  303.     PRFsyncFN fsync;                /* flush all buffers to permanent store     */
  304.     PRSeekFN seek;                  /* position the file to the desired place   */
  305.     PRSeek64FN seek64;              /*           ditto, 64 bit                  */
  306.     PRFileInfoFN fileInfo;          /* Get information about an open file       */
  307.     PRFileInfo64FN fileInfo64;      /*           ditto, 64 bit                  */
  308.     PRWritevFN writev;              /* Write segments as described by iovector  */
  309.     PRConnectFN connect;            /* Connect to the specified (net) address   */
  310.     PRAcceptFN accept;              /* Accept a connection for a (net) peer     */
  311.     PRBindFN bind;                  /* Associate a (net) address with the fd    */
  312.     PRListenFN listen;              /* Prepare to listen for (net) connections  */
  313.     PRShutdownFN shutdown;          /* Shutdown a (net) connection              */
  314.     PRRecvFN recv;                  /* Solicit up the the specified bytes       */
  315.     PRSendFN send;                  /* Send all the bytes specified             */
  316.     PRRecvfromFN recvfrom;          /* Solicit (net) bytes and report source    */
  317.     PRSendtoFN sendto;              /* Send bytes to (net) address specified    */
  318.     PRPollFN poll;                  /* Test the fd to see if it is ready        */
  319.     PRAcceptreadFN acceptread;      /* Accept and read on a new (net) fd        */
  320.     PRTransmitfileFN transmitfile;  /* Transmit at entire file                  */
  321.     PRGetsocknameFN getsockname;    /* Get (net) address associated with fd     */
  322.     PRGetpeernameFN getpeername;    /* Get peer's (net) address                 */
  323.     PRGetsockoptFN getsockopt;      /*             OBSOLETE                     */
  324.     PRSetsockoptFN setsockopt;      /*             OBSOLETE                     */
  325.     PRGetsocketoptionFN getsocketoption;
  326.                                     /* Get current setting of specified option  */
  327.     PRSetsocketoptionFN setsocketoption;
  328.                                     /* Set value of specified option            */
  329. };
  330.  
  331. /*
  332.  **************************************************************************
  333.  * FUNCTION: PR_GetSpecialFD
  334.  * DESCRIPTION: Get the file descriptor that represents the standard input,
  335.  *              output, or error stream.
  336.  * INPUTS:
  337.  *     PRSpecialFD id
  338.  *         A value indicating the type of stream desired:
  339.  *             PR_StandardInput: standard input
  340.  *             PR_StandardOuput: standard output
  341.  *             PR_StandardError: standard error
  342.  * OUTPUTS: none
  343.  * RETURNS: PRFileDesc *
  344.  *     If the argument is valid, PR_GetSpecialFD returns a file descriptor
  345.  *     that represents the corresponding standard I/O stream.  Otherwise,
  346.  *     PR_GetSpecialFD returns NULL and sets error PR_INVALID_ARGUMENT_ERROR.
  347.  **************************************************************************
  348.  */
  349.  
  350. typedef enum PRSpecialFD
  351. {
  352.     PR_StandardInput,          /* standard input */
  353.     PR_StandardOutput,         /* standard output */
  354.     PR_StandardError           /* standard error */
  355. } PRSpecialFD;
  356.  
  357. PR_EXTERN(PRFileDesc*) PR_GetSpecialFD(PRSpecialFD id);
  358.  
  359. #define PR_STDIN    PR_GetSpecialFD(PR_StandardInput)
  360. #define PR_STDOUT    PR_GetSpecialFD(PR_StandardOutput)
  361. #define PR_STDERR    PR_GetSpecialFD(PR_StandardError)
  362.  
  363. /*
  364.  **************************************************************************
  365.  * Layering file descriptors
  366.  *
  367.  * File descriptors may be layered. Each layer has it's own identity.
  368.  * Identities are allocated by the runtime and are to be associated
  369.  * (by the layer implementor) with all layers that are of that type.
  370.  * It is then possible to scan the chain of layers and find a layer
  371.  * that one recongizes and therefore predict that it will implement
  372.  * a desired protocol.
  373.  *
  374.  * There are two well-known identities:
  375.  *      PR_TOP_IO_LAYER     => the identity of the top of the stack
  376.  *      PR_NSPR_IO_LAYER    => the identity used by NSPR proper
  377.  * The latter may be used as a shorthand for identifying the topmost layer
  378.  * of an existing stack. Ie., the following two constructs are equivalent.
  379.  *
  380.  *      rv = PR_PushIOLayer(stack, PR_TOP_IO_LAYER, my_layer);
  381.  *      rv = PR_PushIOLayer(stack, PR_GetLayersIdentity(stack), my_layer)
  382.  *
  383.  * A string may be associated with the creation of the identity. It
  384.  * will be copied by the runtime. If queried the runtime will return
  385.  * a reference to that copied string (not yet another copy). There
  386.  * is no facility for deleting an identity.
  387.  **************************************************************************
  388.  */
  389.  
  390. #define PR_INVALID_IO_LAYER (PRDescIdentity)-1
  391. #define PR_TOP_IO_LAYER (PRDescIdentity)-2
  392. #define PR_NSPR_IO_LAYER (PRDescIdentity)0
  393.  
  394. PR_EXTERN(PRDescIdentity) PR_GetUniqueIdentity(const char *layer_name);
  395. PR_EXTERN(const char*) PR_GetNameForIdentity(PRDescIdentity ident);
  396. PR_EXTERN(PRDescIdentity) PR_GetLayersIdentity(PRFileDesc* fd);
  397. PR_EXTERN(PRFileDesc*) PR_GetIdentitiesLayer(PRFileDesc* stack, PRDescIdentity id);
  398.  
  399. /*
  400.  **************************************************************************
  401.  * PR_GetDefaultIOMethods: Accessing the default methods table.
  402.  * You may get a pointer to the default methods table by calling this function.
  403.  * You may then select any elements from that table with which to build your
  404.  * layer's methods table. You may NOT modify the table directly.
  405.  **************************************************************************
  406.  */
  407. PR_EXTERN(PRIOMethods const*) PR_GetDefaultIOMethods(void);
  408.  
  409. /*
  410.  **************************************************************************
  411.  * Creating a layer
  412.  *
  413.  * A new layer may be allocated by calling PR_CreateIOLayerStub(). The
  414.  * file descriptor returned will contain the pointer to the methods table
  415.  * provided. The runtime will not modify the table nor test its correctness.
  416.  **************************************************************************
  417.  */
  418. PR_EXTERN(PRFileDesc*) PR_CreateIOLayerStub(
  419.     PRDescIdentity ident, PRIOMethods const *methods);
  420.  
  421. /*
  422.  **************************************************************************
  423.  * Pushing a layer
  424.  *
  425.  * A file descriptor (perhaps allocated using PR_CreateIOLayerStub()) may
  426.  * be pushed into an existing stack of file descriptors at any point the
  427.  * caller deems appropriate. The new layer will be inserted into the stack
  428.  * just above the layer with the indicated identity.
  429.  *
  430.  * Note: Even if the identity parameter indicates the top-most layer of
  431.  * the stack, the value of the file descriptor describing the original
  432.  * stack will not change.
  433.  **************************************************************************
  434.  */
  435. PR_EXTERN(PRStatus) PR_PushIOLayer(
  436.     PRFileDesc *stack, PRDescIdentity id, PRFileDesc *layer);
  437.  
  438. /*
  439.  **************************************************************************
  440.  * Popping a layer
  441.  *
  442.  * A layer may be popped from a stack by indicating the identity of the
  443.  * layer to be removed. If found, a pointer to the removed object will
  444.  * be returned to the caller. The object then becomes the responsibility
  445.  * of the caller.
  446.  *
  447.  * Note: Even if the identity indicates the top layer of the stack, the
  448.  * reference returned will not be the file descriptor for the stack and
  449.  * that file descriptor will remain valid.
  450.  **************************************************************************
  451.  */
  452. PR_EXTERN(PRFileDesc*) PR_PopIOLayer(PRFileDesc *stack, PRDescIdentity id);
  453.  
  454. /*
  455.  **************************************************************************
  456.  * FUNCTION:    PR_Open
  457.  * DESCRIPTION:    Open a file for reading, writing, or both.
  458.  * INPUTS:
  459.  *     const char *name
  460.  *         The path name of the file to be opened
  461.  *     PRIntn flags
  462.  *         The file status flags.
  463.  *         It is a bitwise OR of the following bit flags (only one of
  464.  *         the first three flags below may be used):
  465.  *        PR_RDONLY        Open for reading only.
  466.  *        PR_WRONLY        Open for writing only.
  467.  *        PR_RDWR          Open for reading and writing.
  468.  *        PR_CREATE_FILE   If the file does not exist, the file is created
  469.  *                              If the file exists, this flag has no effect.
  470.  *      PR_SYNC          If set, each write will wait for both the file data
  471.  *                              and file status to be physically updated.
  472.  *        PR_APPEND        The file pointer is set to the end of
  473.  *                              the file prior to each write.
  474.  *        PR_TRUNCATE      If the file exists, its length is truncated to 0.
  475.  *
  476.  *     PRIntn mode
  477.  *         The access permission bits of the file mode, if the file is
  478.  *         created when PR_CREATE_FILE is on.
  479.  * OUTPUTS:    None
  480.  * RETURNS:    PRFileDesc *
  481.  *     If the file is successfully opened,
  482.  *     returns a pointer to the PRFileDesc
  483.  *     created for the newly opened file.
  484.  *     Returns a NULL pointer if the open
  485.  *     failed.
  486.  * SIDE EFFECTS:
  487.  * RESTRICTIONS:
  488.  * MEMORY:
  489.  *     The return value, if not NULL, points to a dynamically allocated
  490.  *     PRFileDesc object.
  491.  * ALGORITHM:
  492.  **************************************************************************
  493.  */
  494.  
  495. PR_EXTERN(PRFileDesc*) PR_Open(const char *name, PRIntn flags, PRIntn mode);
  496. /* Open flags */
  497. #define PR_RDONLY       0x01
  498. #define PR_WRONLY       0x02
  499. #define PR_RDWR         0x04
  500. #define PR_CREATE_FILE  0x08
  501. #define PR_APPEND       0x10
  502. #define PR_TRUNCATE     0x20
  503. #define PR_SYNC         0x40
  504.  
  505. /*
  506. ** File modes ....
  507. **
  508. ** CAVEAT: 'mode' is currently only applicable on UNIX platforms. We are
  509. ** still in the process of seeing how these apply to other file systems.
  510. **
  511. **   00400   Read by owner.
  512. **   00200   Write by owner.
  513. **   00100   Execute (search if a directory) by owner.
  514. **   00040   Read by group.
  515. **   00020   Write by group.
  516. **   00010   Execute by group.
  517. **   00004   Read by others.
  518. **   00002   Write by others
  519. **   00001   Execute by others.
  520. **
  521. */
  522.  
  523. /*
  524.  **************************************************************************
  525.  * FUNCTION: PR_Close
  526.  * DESCRIPTION:
  527.  *     Close a file or socket.
  528.  * INPUTS:
  529.  *     PRFileDesc *fd
  530.  *         a pointer to a PRFileDesc.
  531.  * OUTPUTS:
  532.  *     None.
  533.  * RETURN:
  534.  *     PRStatus
  535.  * SIDE EFFECTS:
  536.  * RESTRICTIONS:
  537.  *     None.
  538.  * MEMORY:
  539.  *     The dynamic memory pointed to by the argument fd is freed.
  540.  **************************************************************************
  541.  */
  542.  
  543. PR_EXTERN(PRStatus)    PR_Close(PRFileDesc *fd);
  544.  
  545. /*
  546.  **************************************************************************
  547.  * FUNCTION: PR_Read
  548.  * DESCRIPTION:
  549.  *     Read bytes from a file or socket.
  550.  *     The operation will block until either an end of stream indication is
  551.  *     encountered, some positive number of bytes are transferred, or there
  552.  *     is an error. No more than 'amount' bytes will be transferred.
  553.  * INPUTS:
  554.  *     PRFileDesc *fd
  555.  *         pointer to the PRFileDesc object for the file or socket
  556.  *     void *buf
  557.  *         pointer to a buffer to hold the data read in.
  558.  *     PRInt32 amount
  559.  *         the size of 'buf' (in bytes)
  560.  * OUTPUTS:
  561.  * RETURN:
  562.  *     PRInt32
  563.  *         a positive number indicates the number of bytes actually read in.
  564.  *         0 means end of file is reached or the network connection is closed.
  565.  *         -1 indicates a failure. The reason for the failure is obtained
  566.  *         by calling PR_GetError().
  567.  * SIDE EFFECTS:
  568.  *     data is written into the buffer pointed to by 'buf'.
  569.  * RESTRICTIONS:
  570.  *     None.
  571.  * MEMORY:
  572.  *     N/A
  573.  * ALGORITHM:
  574.  *     N/A
  575.  **************************************************************************
  576.  */
  577.  
  578. PR_EXTERN(PRInt32) PR_Read(PRFileDesc *fd, void *buf, PRInt32 amount);
  579.  
  580. /*
  581.  ***************************************************************************
  582.  * FUNCTION: PR_Write
  583.  * DESCRIPTION:
  584.  *     Write a specified number of bytes to a file or socket.  The thread
  585.  *     invoking this function blocks until all the data is written.
  586.  * INPUTS:
  587.  *     PRFileDesc *fd
  588.  *         pointer to a PRFileDesc object that refers to a file or socket
  589.  *     const void *buf
  590.  *         pointer to the buffer holding the data
  591.  *     PRInt32 amount
  592.  *         amount of data in bytes to be written from the buffer
  593.  * OUTPUTS:
  594.  *     None.
  595.  * RETURN: PRInt32
  596.  *     A positive number indicates the number of bytes successfully written.
  597.  *     A -1 is an indication that the operation failed. The reason
  598.  *     for the failure is obtained by calling PR_GetError().
  599.  ***************************************************************************
  600.  */
  601.  
  602. PR_EXTERN(PRInt32) PR_Write(PRFileDesc *fd,const void *buf,PRInt32 amount);
  603.  
  604. /*
  605.  ***************************************************************************
  606.  * FUNCTION: PR_Writev
  607.  * DESCRIPTION:
  608.  *     Write data to a socket.  The data is organized in a PRIOVec array. The
  609.  *     operation will block until all the data is written or the operation
  610.  *     fails.
  611.  * INPUTS:
  612.  *     PRFileDesc *fd
  613.  *         Pointer that points to a PRFileDesc object for a socket.
  614.  *     PRIOVec *iov
  615.  *         An array of PRIOVec.  PRIOVec is a struct with the following
  616.  *         two fields:
  617.  *             char *iov_base;
  618.  *             int iov_len;
  619.  *     PRInt32 iov_size
  620.  *         Number of elements in the iov array. The value of this
  621.  *         argument must not be greater than PR_MAX_IOVECTOR_SIZE.
  622.  *         If it is, the method will fail (PR_BUFFER_OVERFLOW_ERROR).
  623.  *     PRIntervalTime timeout
  624.  *       Time limit for completion of the entire write operation.
  625.  * OUTPUTS:
  626.  *     None
  627.  * RETURN:
  628.  *     A positive number indicates the number of bytes successfully written.
  629.  *     A -1 is an indication that the operation failed. The reason
  630.  *     for the failure is obtained by calling PR_GetError().
  631.  ***************************************************************************
  632.  */
  633.  
  634. #define PR_MAX_IOVECTOR_SIZE 16   /* 'size' must be <= */
  635.  
  636. PR_EXTERN(PRInt32) PR_Writev(
  637.     PRFileDesc *fd, PRIOVec *iov, PRInt32 size, PRIntervalTime timeout);
  638.  
  639. /*
  640.  ***************************************************************************
  641.  * FUNCTION: PR_Delete
  642.  * DESCRIPTION:
  643.  *     Delete a file from the filesystem. The operation may fail if the
  644.  *     file is open.
  645.  * INPUTS:
  646.  *     const char *name
  647.  *         Path name of the file to be deleted.
  648.  * OUTPUTS:
  649.  *     None.
  650.  * RETURN: PRStatus
  651.  *     The function returns PR_SUCCESS if the file is successfully
  652.  *     deleted, otherwise it returns PR_FAILURE.
  653.  ***************************************************************************
  654.  */
  655.  
  656. PR_EXTERN(PRStatus) PR_Delete(const char *name);
  657.  
  658. /**************************************************************************/
  659.  
  660. typedef enum PRFileType
  661. {
  662.     PR_FILE_FILE = 1,
  663.     PR_FILE_DIRECTORY = 2,
  664.     PR_FILE_OTHER = 3
  665. } PRFileType;
  666.  
  667. struct PRFileInfo {
  668.     PRFileType type;        /* Type of file */
  669.     PRUint32 size;          /* Size, in bytes, of file's contents */
  670.     PRTime creationTime;    /* Creation time per definition of PRTime */
  671.     PRTime modifyTime;      /* Last modification time per definition of PRTime */
  672. };
  673.  
  674. struct PRFileInfo64 {
  675.     PRFileType type;        /* Type of file */
  676.     PRUint64 size;          /* Size, in bytes, of file's contents */
  677.     PRTime creationTime;    /* Creation time per definition of PRTime */
  678.     PRTime modifyTime;      /* Last modification time per definition of PRTime */
  679. };
  680.  
  681. /****************************************************************************
  682.  * FUNCTION: PR_GetFileInfo, PR_GetFileInfo64
  683.  * DESCRIPTION:
  684.  *     Get the information about the file with the given path name. This is
  685.  *     applicable only to NSFileDesc describing 'file' types (see
  686.  * INPUTS:
  687.  *     const char *fn
  688.  *         path name of the file
  689.  * OUTPUTS:
  690.  *     PRFileInfo *info
  691.  *         Information about the given file is written into the file
  692.  *         information object pointer to by 'info'.
  693.  * RETURN: PRStatus
  694.  *     PR_GetFileInfo returns PR_SUCCESS if file information is successfully
  695.  *     obtained, otherwise it returns PR_FAILURE.
  696.  ***************************************************************************
  697.  */
  698.  
  699. PR_EXTERN(PRStatus) PR_GetFileInfo(const char *fn, PRFileInfo *info);
  700. PR_EXTERN(PRStatus) PR_GetFileInfo64(const char *fn, PRFileInfo64 *info);
  701.  
  702. /*
  703.  **************************************************************************
  704.  * FUNCTION: PR_GetOpenFileInfo, PR_GetOpenFileInfo64
  705.  * DESCRIPTION:
  706.  *     Get information about an open file referred to by the
  707.  *     given PRFileDesc object.
  708.  * INPUTS:
  709.  *     const PRFileDesc *fd
  710.  *          A reference to a valid, open file.
  711.  * OUTPUTS:
  712.  *     Same as PR_GetFileInfo, PR_GetFileInfo64
  713.  * RETURN: PRStatus
  714.  *     PR_GetFileInfo returns PR_SUCCESS if file information is successfully
  715.  *     obtained, otherwise it returns PR_FAILURE.
  716.  ***************************************************************************
  717.  */
  718.  
  719. PR_EXTERN(PRStatus) PR_GetOpenFileInfo(PRFileDesc *fd, PRFileInfo *info);
  720. PR_EXTERN(PRStatus) PR_GetOpenFileInfo64(PRFileDesc *fd, PRFileInfo64 *info);
  721.  
  722. /*
  723.  **************************************************************************
  724.  * FUNCTION: PR_Rename
  725.  * DESCRIPTION:
  726.  *     Rename a file from the old name 'from' to the new name 'to'.
  727.  * INPUTS:
  728.  *     const char *from
  729.  *         The old name of the file to be renamed.
  730.  *     const char *to
  731.  *         The new name of the file.
  732.  * OUTPUTS:
  733.  *     None.
  734.  * RETURN: PRStatus
  735.  **************************************************************************
  736.  */
  737.  
  738. PR_EXTERN(PRStatus)    PR_Rename(const char *from, const char *to);
  739.  
  740. /*
  741.  *************************************************************************
  742.  * FUNCTION: PR_Access
  743.  * DESCRIPTION:
  744.  *     Determine accessibility of a file.
  745.  * INPUTS:
  746.  *     const char *name
  747.  *         path name of the file
  748.  *     PRAccessHow how
  749.  *         specifies which access permission to check for.
  750.  *         It can be one of the following values:
  751.  *             PR_ACCESS_READ_OK       Test for read permission
  752.  *             PR_ACCESS_WRITE_OK      Test for write permission
  753.  *             PR_ACCESS_EXISTS        Check existence of file
  754.  * OUTPUTS:
  755.  *     None.
  756.  * RETURN: PRStatus
  757.  *     PR_SUCCESS is returned if the requested access is permitted.
  758.  *     Otherwise, PR_FAILURE is returned. Additional information
  759.  *     regarding the reason for the failure may be retrieved from
  760.  *     PR_GetError().
  761.  *************************************************************************
  762.  */
  763.  
  764. typedef enum PRAccessHow {
  765.     PR_ACCESS_EXISTS = 1,
  766.     PR_ACCESS_WRITE_OK = 2,
  767.     PR_ACCESS_READ_OK = 3
  768. } PRAccessHow;
  769.  
  770. PR_EXTERN(PRStatus) PR_Access(const char *name, PRAccessHow how);
  771.  
  772. /*
  773.  *************************************************************************
  774.  * FUNCTION: PR_Seek, PR_Seek64
  775.  * DESCRIPTION:
  776.  *     Moves read-write file offset
  777.  * INPUTS:
  778.  *     PRFileDesc *fd
  779.  *         Pointer to a PRFileDesc object.
  780.  *     PRInt32, PRInt64 offset
  781.  *         Specifies a value, in bytes, that is used in conjunction
  782.  *         with the 'whence' parameter to set the file pointer.  A
  783.  *         negative value causes seeking in the reverse direction.
  784.  *     PRSeekWhence whence
  785.  *         Specifies how to interpret the 'offset' parameter in setting
  786.  *         the file pointer associated with the 'fd' parameter.
  787.  *         Values for the 'whence' parameter are:
  788.  *             PR_SEEK_SET  Sets the file pointer to the value of the
  789.  *                          'offset' parameter
  790.  *             PR_SEEK_CUR  Sets the file pointer to its current location
  791.  *                          plus the value of the offset parameter.
  792.  *             PR_SEEK_END  Sets the file pointer to the size of the
  793.  *                          file plus the value of the offset parameter.
  794.  * OUTPUTS:
  795.  *     None.
  796.  * RETURN: PRInt32, PRInt64
  797.  *     Upon successful completion, the resulting pointer location,
  798.  *     measured in bytes from the beginning of the file, is returned.
  799.  *     If the PR_Seek() function fails, the file offset remains
  800.  *     unchanged, and the returned value is -1. The error code can
  801.  *     then be retrieved via PR_GetError().
  802.  *************************************************************************
  803.  */
  804.  
  805. PR_EXTERN(PRInt32) PR_Seek(PRFileDesc *fd, PRInt32 offset, PRSeekWhence whence);
  806. PR_EXTERN(PRInt64) PR_Seek64(PRFileDesc *fd, PRInt64 offset, PRSeekWhence whence);
  807.  
  808. /*
  809.  ************************************************************************
  810.  * FUNCTION: PR_Available
  811.  * DESCRIPTION:
  812.  *     Determine the amount of data in bytes available for reading
  813.  *     in the given file or socket.
  814.  * INPUTS:
  815.  *     PRFileDesc *fd
  816.  *         Pointer to a PRFileDesc object that refers to a file or
  817.  *         socket.
  818.  * OUTPUTS:
  819.  *     None
  820.  * RETURN: PRInt32, PRInt64
  821.  *     Upon successful completion, PR_Available returns the number of
  822.  *     bytes beyond the current read pointer that is available for
  823.  *     reading.  Otherwise, it returns a -1 and the reason for the
  824.  *     failure can be retrieved via PR_GetError().
  825.  ************************************************************************
  826.  */
  827.  
  828. PR_EXTERN(PRInt32) PR_Available(PRFileDesc *fd);
  829. PR_EXTERN(PRInt64) PR_Available64(PRFileDesc *fd);
  830.  
  831. /*
  832.  ************************************************************************
  833.  * FUNCTION: PR_Sync
  834.  * DESCRIPTION:
  835.  *     Sync any buffered data for a fd to its backing device (disk).
  836.  * INPUTS:
  837.  *     PRFileDesc *fd
  838.  *         Pointer to a PRFileDesc object that refers to a file or
  839.  *         socket
  840.  * OUTPUTS:
  841.  *     None
  842.  * RETURN: PRStatus
  843.  *     PR_SUCCESS is returned if the requested access is permitted.
  844.  *     Otherwise, PR_FAILURE is returned.
  845.  ************************************************************************
  846.  */
  847.  
  848. PR_EXTERN(PRStatus)    PR_Sync(PRFileDesc *fd);
  849.  
  850. /************************************************************************/
  851.  
  852. struct PRDirEntry {
  853.     const char *name;        /* name of entry, relative to directory name */
  854. };
  855.  
  856. #if !defined(NO_NSPR_10_SUPPORT)
  857. #define PR_DirName(dirEntry)    (dirEntry->name)
  858. #endif
  859.  
  860. /*
  861.  *************************************************************************
  862.  * FUNCTION: PR_OpenDir
  863.  * DESCRIPTION:
  864.  *     Open the directory by the given name
  865.  * INPUTS:
  866.  *     const char *name
  867.  *         path name of the directory to be opened
  868.  * OUTPUTS:
  869.  *     None
  870.  * RETURN: PRDir *
  871.  *     If the directory is sucessfully opened, a PRDir object is
  872.  *     dynamically allocated and a pointer to it is returned.
  873.  *     If the directory cannot be opened, a NULL pointer is returned.
  874.  * MEMORY:
  875.  *     Upon successful completion, the return value points to
  876.  *     dynamically allocated memory.
  877.  *************************************************************************
  878.  */
  879.  
  880. PR_EXTERN(PRDir*) PR_OpenDir(const char *name);
  881.  
  882. /*
  883.  *************************************************************************
  884.  * FUNCTION: PR_ReadDir
  885.  * DESCRIPTION:
  886.  * INPUTS:
  887.  *     PRDir *dir
  888.  *         pointer to a PRDir object that designates an open directory
  889.  *     PRDirFlags flags
  890.  *           PR_SKIP_NONE     Do not skip any files
  891.  *           PR_SKIP_DOT      Skip the directory entry "." that
  892.  *                            represents the current directory
  893.  *           PR_SKIP_DOT_DOT  Skip the directory entry ".." that
  894.  *                            represents the parent directory.
  895.  *           PR_SKIP_BOTH     Skip both '.' and '..'
  896.  *           PR_SKIP_HIDDEN   Skip hidden files
  897.  * OUTPUTS:
  898.  * RETURN: PRDirEntry*
  899.  *     Returns a pointer to the next entry in the directory.  Returns
  900.  *     a NULL pointer upon reaching the end of the directory or when an
  901.  *     error occurs. The actual reason can be retrieved via PR_GetError().
  902.  *************************************************************************
  903.  */
  904.  
  905. typedef enum PRDirFlags {
  906.     PR_SKIP_NONE = 0x0,
  907.     PR_SKIP_DOT = 0x1,
  908.     PR_SKIP_DOT_DOT = 0x2,
  909.     PR_SKIP_BOTH = 0x3,
  910.     PR_SKIP_HIDDEN = 0x4
  911. } PRDirFlags;
  912.  
  913. PR_EXTERN(PRDirEntry*) PR_ReadDir(PRDir *dir, PRDirFlags flags);
  914.  
  915. /*
  916.  *************************************************************************
  917.  * FUNCTION: PR_CloseDir
  918.  * DESCRIPTION:
  919.  *     Close the specified directory.
  920.  * INPUTS:
  921.  *     PRDir *dir
  922.  *        The directory to be closed.
  923.  * OUTPUTS:
  924.  *     None
  925.  * RETURN: PRStatus
  926.  *        If successful, will return a status of PR_SUCCESS. Otherwise
  927.  *        a value of PR_FAILURE. The reason for the failure may be re-
  928.  *        trieved using PR_GetError().
  929.  *************************************************************************
  930.  */
  931.  
  932. PR_EXTERN(PRStatus) PR_CloseDir(PRDir *dir);
  933.  
  934. /*
  935.  *************************************************************************
  936.  * FUNCTION: PR_MkDir
  937.  * DESCRIPTION:
  938.  *     Create a new directory with the given name and access mode.
  939.  * INPUTS:
  940.  *     const char *name
  941.  *        The name of the directory to be created. All the path components
  942.  *        up to but not including the leaf component must already exist.
  943.  *     PRIntn mode
  944.  *        See 'mode' definiton in PR_Open().
  945.  * OUTPUTS:
  946.  *     None
  947.  * RETURN: PRStatus
  948.  *        If successful, will return a status of PR_SUCCESS. Otherwise
  949.  *        a value of PR_FAILURE. The reason for the failure may be re-
  950.  *        trieved using PR_GetError().
  951.  *************************************************************************
  952.  */
  953.  
  954. PR_EXTERN(PRStatus) PR_MkDir(const char *name, PRIntn mode);
  955.  
  956. /*
  957.  *************************************************************************
  958.  * FUNCTION: PR_RmDir
  959.  * DESCRIPTION:
  960.  *     Remove a directory by the given name.
  961.  * INPUTS:
  962.  *     const char *name
  963.  *        The name of the directory to be removed. All the path components
  964.  *        must already exist. Only the leaf component will be removed.
  965.  * OUTPUTS:
  966.  *     None
  967.  * RETURN: PRStatus
  968.  *        If successful, will return a status of PR_SUCCESS. Otherwise
  969.  *        a value of PR_FAILURE. The reason for the failure may be re-
  970.  *        trieved using PR_GetError().
  971.  **************************************************************************
  972.  */
  973.  
  974. PR_EXTERN(PRStatus) PR_RmDir(const char *name);
  975.  
  976. PR_EXTERN(PRUintn) PR_NetAddrSize(const PRNetAddr* addr);
  977.  
  978. /*
  979.  *************************************************************************
  980.  * FUNCTION: PR_NewUDPSocket
  981.  * DESCRIPTION:
  982.  *     Create a new UDP network connection.
  983.  * INPUTS:
  984.  *     None
  985.  * OUTPUTS:
  986.  *     None
  987.  * RETURN: PRFileDesc*
  988.  *     Upon successful completion, PR_NewUDPSocket returns a pointer
  989.  *     to the PRFileDesc created for the newly opened UDP socket.
  990.  *     Returns a NULL pointer if the create of a new UDP connection failed.
  991.  *
  992.  **************************************************************************
  993.  */
  994.  
  995. PR_EXTERN(PRFileDesc*)    PR_NewUDPSocket(void);
  996.  
  997. /*
  998.  *************************************************************************
  999.  * FUNCTION: PR_NewTCPSocket
  1000.  * DESCRIPTION:
  1001.  *     Create a new TCP network connection.
  1002.  * INPUTS:
  1003.  *     None
  1004.  * OUTPUTS:
  1005.  *     None
  1006.  * RETURN: PRFileDesc*
  1007.  *     Upon successful completion, PR_NewTCPSocket returns a pointer
  1008.  *     to the PRFileDesc created for the newly opened TCP socket.
  1009.  *     Returns a NULL pointer if the create of a new TCP connection failed.
  1010.  *
  1011.  **************************************************************************
  1012.  */
  1013.  
  1014. PR_EXTERN(PRFileDesc*)    PR_NewTCPSocket(void);
  1015.  
  1016. /*
  1017.  *************************************************************************
  1018.  * FUNCTION: PR_Connect
  1019.  * DESCRIPTION:
  1020.  *     Initiate a connection on a socket.
  1021.  * INPUTS:
  1022.  *     PRFileDesc *fd
  1023.  *       Points to a PRFileDesc object representing a socket
  1024.  *     PRNetAddr *addr
  1025.  *       Specifies the address of the socket in its own communication
  1026.  *       space.
  1027.  *     PRIntervalTime timeout
  1028.  *       Time limit for completion of the connect operation.
  1029.  * OUTPUTS:
  1030.  *     None
  1031.  * RETURN: PRStatus
  1032.  *     Upon successful completion of connection initiation, PR_Connect
  1033.  *     returns PR_SUCCESS.  Otherwise, it returns PR_FAILURE.  Further
  1034.  *     failure information can be obtained by calling PR_GetError().
  1035.  **************************************************************************
  1036.  */
  1037.  
  1038. PR_EXTERN(PRStatus) PR_Connect(
  1039.     PRFileDesc *fd, const PRNetAddr *addr, PRIntervalTime timeout);
  1040.  
  1041. /*
  1042.  *************************************************************************
  1043.  * FUNCTION: PR_GetConnectStatus
  1044.  * DESCRIPTION:
  1045.  *     Get the completion status of a nonblocking connect.  After
  1046.  *     a nonblocking connect is initiated with PR_Connect() (which
  1047.  *     fails with PR_IN_PROGRESS_ERROR), one should call PR_Poll()
  1048.  *     on the socket, with the in_flags PR_POLL_WRITE | PR_POLL_EXCEPT.
  1049.  *     When PR_Poll() returns, one calls PR_GetConnectStatus on the
  1050.  *     PRPollDesc structure to determine whether the nonblocking
  1051.  *     connect has succeeded or failed.
  1052.  * INPUTS:
  1053.  *     const PRPollDesc *pd
  1054.  *         Pointer to a PRPollDesc whose fd member is the socket,
  1055.  *         and in_flags must contain PR_POLL_WRITE and PR_POLL_EXCEPT.
  1056.  *         PR_Poll() should have been called and set the out_flags.
  1057.  * RETURN: PRStatus
  1058.  *     If the nonblocking connect has successfully completed,
  1059.  *     PR_GetConnectStatus returns PR_SUCCESS.  If PR_GetConnectStatus()
  1060.  *     returns PR_FAILURE, call PR_GetError():
  1061.  *     - PR_IN_PROGRESS_ERROR: the nonblocking connect is still in
  1062.  *       progress and has not completed yet.
  1063.  *     - Other errors: the nonblocking connect has failed with this
  1064.  *       error code.
  1065.  */
  1066.  
  1067. PR_EXTERN(PRStatus)    PR_GetConnectStatus(const PRPollDesc *pd);
  1068.  
  1069. /*
  1070.  *************************************************************************
  1071.  * FUNCTION: PR_Accept
  1072.  * DESCRIPTION:
  1073.  *     Accept a connection on a socket.
  1074.  * INPUTS:
  1075.  *     PRFileDesc *fd
  1076.  *       Points to a PRFileDesc object representing the rendezvous socket
  1077.  *       on which the caller is willing to accept new connections.
  1078.  *     PRIntervalTime timeout
  1079.  *       Time limit for completion of the accept operation.
  1080.  * OUTPUTS:
  1081.  *     PRNetAddr *addr
  1082.  *       Returns the address of the connecting entity in its own
  1083.  *       communication space. It may be NULL.
  1084.  * RETURN: PRFileDesc*
  1085.  *     Upon successful acceptance of a connection, PR_Accept
  1086.  *     returns a valid file descriptor. Otherwise, it returns NULL.
  1087.  *     Further failure information can be obtained by calling PR_GetError().
  1088.  **************************************************************************
  1089.  */
  1090.  
  1091. PR_EXTERN(PRFileDesc*) PR_Accept(
  1092.     PRFileDesc *fd, PRNetAddr *addr, PRIntervalTime timeout);
  1093.  
  1094. /*
  1095.  *************************************************************************
  1096.  * FUNCTION: PR_Bind
  1097.  * DESCRIPTION:
  1098.  *    Bind an address to a socket.
  1099.  * INPUTS:
  1100.  *     PRFileDesc *fd
  1101.  *       Points to a PRFileDesc object representing a socket.
  1102.  *     PRNetAddr *addr
  1103.  *       Specifies the address to which the socket will be bound.
  1104.  * OUTPUTS:
  1105.  *     None
  1106.  * RETURN: PRStatus
  1107.  *     Upon successful binding of an address to a socket, PR_Bind
  1108.  *     returns PR_SUCCESS.  Otherwise, it returns PR_FAILURE.  Further
  1109.  *     failure information can be obtained by calling PR_GetError().
  1110.  **************************************************************************
  1111.  */
  1112.  
  1113. PR_EXTERN(PRStatus) PR_Bind(PRFileDesc *fd, const PRNetAddr *addr);
  1114.  
  1115. /*
  1116.  *************************************************************************
  1117.  * FUNCTION: PR_Listen
  1118.  * DESCRIPTION:
  1119.  *    Listen for connections on a socket.
  1120.  * INPUTS:
  1121.  *     PRFileDesc *fd
  1122.  *       Points to a PRFileDesc object representing a socket that will be
  1123.  *       used to listen for new connections.
  1124.  *     PRIntn backlog
  1125.  *       Specifies the maximum length of the queue of pending connections.
  1126.  * OUTPUTS:
  1127.  *     None
  1128.  * RETURN: PRStatus
  1129.  *     Upon successful completion of listen request, PR_Listen
  1130.  *     returns PR_SUCCESS.  Otherwise, it returns PR_FAILURE.  Further
  1131.  *     failure information can be obtained by calling PR_GetError().
  1132.  **************************************************************************
  1133.  */
  1134.  
  1135. PR_EXTERN(PRStatus) PR_Listen(PRFileDesc *fd, PRIntn backlog);
  1136.  
  1137. /*
  1138.  *************************************************************************
  1139.  * FUNCTION: PR_Shutdown
  1140.  * DESCRIPTION:
  1141.  *    Shut down part of a full-duplex connection on a socket.
  1142.  * INPUTS:
  1143.  *     PRFileDesc *fd
  1144.  *       Points to a PRFileDesc object representing a connected socket.
  1145.  *     PRIntn how
  1146.  *       Specifies the kind of disallowed operations on the socket.
  1147.  *           PR_SHUTDOWN_RCV - Further receives will be disallowed
  1148.  *           PR_SHUTDOWN_SEND - Further sends will be disallowed
  1149.  *           PR_SHUTDOWN_BOTH - Further sends and receives will be disallowed
  1150.  * OUTPUTS:
  1151.  *     None
  1152.  * RETURN: PRStatus
  1153.  *     Upon successful completion of shutdown request, PR_Shutdown
  1154.  *     returns PR_SUCCESS.  Otherwise, it returns PR_FAILURE.  Further
  1155.  *     failure information can be obtained by calling PR_GetError().
  1156.  **************************************************************************
  1157.  */
  1158.  
  1159. typedef enum PRShutdownHow
  1160. {
  1161.     PR_SHUTDOWN_RCV = 0,      /* disallow further receives */
  1162.     PR_SHUTDOWN_SEND = 1,     /* disallow further sends */
  1163.     PR_SHUTDOWN_BOTH = 2      /* disallow further receives and sends */
  1164. } PRShutdownHow;
  1165.  
  1166. PR_EXTERN(PRStatus)    PR_Shutdown(PRFileDesc *fd, PRShutdownHow how);
  1167.  
  1168. /*
  1169.  *************************************************************************
  1170.  * FUNCTION: PR_Recv
  1171.  * DESCRIPTION:
  1172.  *    Receive a specified number of bytes from a connected socket.
  1173.  *     The operation will block until some positive number of bytes are 
  1174.  *     transferred, a time out has occurred, or there is an error. 
  1175.  *     No more than 'amount' bytes will be transferred.
  1176.  * INPUTS:
  1177.  *     PRFileDesc *fd
  1178.  *       points to a PRFileDesc object representing a socket.
  1179.  *     void *buf
  1180.  *       pointer to a buffer to hold the data received.
  1181.  *     PRInt32 amount
  1182.  *       the size of 'buf' (in bytes)
  1183.  *     PRIntn flags
  1184.  *        (OBSOLETE - must always be zero)
  1185.  *     PRIntervalTime timeout
  1186.  *       Time limit for completion of the receive operation.
  1187.  * OUTPUTS:
  1188.  *     None
  1189.  * RETURN: PRInt32
  1190.  *         a positive number indicates the number of bytes actually received.
  1191.  *         0 means the network connection is closed.
  1192.  *         -1 indicates a failure. The reason for the failure is obtained
  1193.  *         by calling PR_GetError().
  1194.  **************************************************************************
  1195.  */
  1196.  
  1197. PR_EXTERN(PRInt32)    PR_Recv(PRFileDesc *fd, void *buf, PRInt32 amount,
  1198.                 PRIntn flags, PRIntervalTime timeout);
  1199.  
  1200. /*
  1201.  *************************************************************************
  1202.  * FUNCTION: PR_Send
  1203.  * DESCRIPTION:
  1204.  *    Send a specified number of bytes from a connected socket.
  1205.  *     The operation will block until all bytes are 
  1206.  *     processed, a time out has occurred, or there is an error. 
  1207.  * INPUTS:
  1208.  *     PRFileDesc *fd
  1209.  *       points to a PRFileDesc object representing a socket.
  1210.  *     void *buf
  1211.  *       pointer to a buffer from where the data is sent.
  1212.  *     PRInt32 amount
  1213.  *       the size of 'buf' (in bytes)
  1214.  *     PRIntn flags
  1215.  *        (OBSOLETE - must always be zero)
  1216.  *     PRIntervalTime timeout
  1217.  *       Time limit for completion of the send operation.
  1218.  * OUTPUTS:
  1219.  *     None
  1220.  * RETURN: PRInt32
  1221.  *     A positive number indicates the number of bytes successfully processed.
  1222.  *     This number must always equal 'amount'. A -1 is an indication that the
  1223.  *     operation failed. The reason for the failure is obtained by calling
  1224.  *     PR_GetError().
  1225.  **************************************************************************
  1226.  */
  1227.  
  1228. PR_EXTERN(PRInt32)    PR_Send(PRFileDesc *fd, const void *buf, PRInt32 amount,
  1229.                                 PRIntn flags, PRIntervalTime timeout);
  1230.  
  1231. /*
  1232.  *************************************************************************
  1233.  * FUNCTION: PR_RecvFrom
  1234.  * DESCRIPTION:
  1235.  *     Receive up to a specified number of bytes from socket which may
  1236.  *     or may not be connected.
  1237.  *     The operation will block until one or more bytes are 
  1238.  *     transferred, a time out has occurred, or there is an error. 
  1239.  *     No more than 'amount' bytes will be transferred.
  1240.  * INPUTS:
  1241.  *     PRFileDesc *fd
  1242.  *       points to a PRFileDesc object representing a socket.
  1243.  *     void *buf
  1244.  *       pointer to a buffer to hold the data received.
  1245.  *     PRInt32 amount
  1246.  *       the size of 'buf' (in bytes)
  1247.  *     PRIntn flags
  1248.  *        (OBSOLETE - must always be zero)
  1249.  *     PRNetAddr *addr
  1250.  *       Specifies the address of the sending peer. It may be NULL.
  1251.  *     PRIntervalTime timeout
  1252.  *       Time limit for completion of the receive operation.
  1253.  * OUTPUTS:
  1254.  *     None
  1255.  * RETURN: PRInt32
  1256.  *         a positive number indicates the number of bytes actually received.
  1257.  *         0 means the network connection is closed.
  1258.  *         -1 indicates a failure. The reason for the failure is obtained
  1259.  *         by calling PR_GetError().
  1260.  **************************************************************************
  1261.  */
  1262.  
  1263. PR_EXTERN(PRInt32) PR_RecvFrom(
  1264.     PRFileDesc *fd, void *buf, PRInt32 amount, PRIntn flags,
  1265.     PRNetAddr *addr, PRIntervalTime timeout);
  1266.  
  1267. /*
  1268.  *************************************************************************
  1269.  * FUNCTION: PR_SendTo
  1270.  * DESCRIPTION:
  1271.  *    Send a specified number of bytes from an unconnected socket.
  1272.  *    The operation will block until all bytes are 
  1273.  *    sent, a time out has occurred, or there is an error. 
  1274.  * INPUTS:
  1275.  *     PRFileDesc *fd
  1276.  *       points to a PRFileDesc object representing an unconnected socket.
  1277.  *     void *buf
  1278.  *       pointer to a buffer from where the data is sent.
  1279.  *     PRInt32 amount
  1280.  *       the size of 'buf' (in bytes)
  1281.  *     PRIntn flags
  1282.  *        (OBSOLETE - must always be zero)
  1283.  *     PRNetAddr *addr
  1284.  *       Specifies the address of the peer.
  1285. .*     PRIntervalTime timeout
  1286.  *       Time limit for completion of the send operation.
  1287.  * OUTPUTS:
  1288.  *     None
  1289.  * RETURN: PRInt32
  1290.  *     A positive number indicates the number of bytes successfully sent.
  1291.  *     -1 indicates a failure. The reason for the failure is obtained
  1292.  *     by calling PR_GetError().
  1293.  **************************************************************************
  1294.  */
  1295.  
  1296. PR_EXTERN(PRInt32) PR_SendTo(
  1297.     PRFileDesc *fd, const void *buf, PRInt32 amount, PRIntn flags,
  1298.     const PRNetAddr *addr, PRIntervalTime timeout);
  1299.  
  1300. /*
  1301. *************************************************************************
  1302. ** FUNCTION: PR_TransmitFile
  1303. ** DESCRIPTION:
  1304. **    Transmitfile sends a complete file (sourceFile) across a socket 
  1305. **    (networkSocket).  If headers is non-NULL, the headers will be sent across
  1306. **    the socket prior to sending the file.
  1307. ** 
  1308. **    Optionally, the PR_TRANSMITFILE_CLOSE_SOCKET flag may be passed to
  1309. **    transmitfile.  This flag specifies that transmitfile should close the
  1310. **    socket after sending the data.
  1311. **
  1312. ** INPUTS:
  1313. **    PRFileDesc *networkSocket
  1314. **        The socket to send data over
  1315. **    PRFileDesc *sourceFile
  1316. **        The file to send
  1317. **    const void *headers
  1318. **        A pointer to headers to be sent before sending data
  1319. **    PRInt32       hlen
  1320. **        length of header buffers in bytes.
  1321. **    PRTransmitFileFlags       flags
  1322. **        If the flags indicate that the connection should be closed,
  1323. **        it will be done immediately after transferring the file, unless
  1324. **        the operation is unsuccessful. 
  1325. .*     PRIntervalTime timeout
  1326.  *        Time limit for completion of the transmit operation.
  1327. **
  1328. ** RETURNS:
  1329. **    Returns the number of bytes written or -1 if the operation failed.
  1330. **    If an error occurs while sending the file, the PR_TRANSMITFILE_CLOSE_
  1331. **    SOCKET flag is ignored. The reason for the failure is obtained
  1332. **    by calling PR_GetError().
  1333. **************************************************************************
  1334. */
  1335.  
  1336. PR_EXTERN(PRInt32) PR_TransmitFile(
  1337.     PRFileDesc *networkSocket, PRFileDesc *sourceFile,
  1338.     const void *headers, PRInt32 hlen, PRTransmitFileFlags flags,
  1339.     PRIntervalTime timeout);
  1340. /*
  1341. *************************************************************************
  1342. ** FUNCTION: PR_AcceptRead
  1343. ** DESCRIPTION:
  1344. **    AcceptRead accepts a new connection, returns the newly created
  1345. **    socket's descriptor and also returns the connecting peer's address.
  1346. **    AcceptRead, as its name suggests, also receives the first block of data 
  1347. **    sent by the peer.
  1348. **
  1349. ** INPUTS:
  1350. **    PRFileDesc *listenSock
  1351. **        A socket descriptor that has been called with the PR_Listen() 
  1352. **        function, also known as the rendezvous socket.
  1353. **    void *buf
  1354. **        A pointer to a buffer to receive data sent by the client.  This 
  1355. **        buffer must be large enough to receive <amount> bytes of data
  1356. **        and two PRNetAddr structures (thus allowing the runtime to align
  1357. **        the addresses as needed).
  1358. **    PRInt32 amount
  1359. **        The number of bytes of client data to receive.  Does not include
  1360. **        the size of the PRNetAddr structures.  If 0, no data will be read
  1361. **        from the client.
  1362. **    PRIntervalTime timeout
  1363. **        The timeout interval only applies to the read portion of the 
  1364. **        operation.  PR_AcceptRead will block indefinitely until the 
  1365. **        connection is accepted; the read will timeout after the timeout 
  1366. **        interval elapses.
  1367. ** OUTPUTS:
  1368. **    PRFileDesc **acceptedSock
  1369. **        The file descriptor for the newly connected socket.  This parameter
  1370. **        will only be valid if the function return does not indicate failure.
  1371. **    PRNetAddr  **peerAddr,
  1372. **        The address of the remote socket.  This parameter will only be
  1373. **        valid if the function return does not indicate failure.
  1374. ** 
  1375. ** RETURNS:
  1376. **     The number of bytes read from the client or -1 on failure.  The reason 
  1377. **     for the failure is obtained by calling PR_GetError().
  1378. **************************************************************************
  1379. **/
  1380. PR_EXTERN(PRInt32) PR_AcceptRead(
  1381.     PRFileDesc *listenSock, PRFileDesc **acceptedSock,
  1382.     PRNetAddr **peerAddr, void *buf, PRInt32 amount, PRIntervalTime timeout);
  1383.  
  1384. /*
  1385. *************************************************************************
  1386. ** FUNCTION: PR_NewTCPSocketPair
  1387. ** DESCRIPTION:
  1388. **    Create a new TCP socket pair. The returned descriptors can be used
  1389. **    interchangeably; they are interconnected full-duplex descriptors: data
  1390. **    written to one can be read from the other and vice-versa.
  1391. **
  1392. ** INPUTS:
  1393. **    None
  1394. ** OUTPUTS:
  1395. **    PRFileDesc *fds[2]
  1396. **        The file descriptor pair for the newly created TCP sockets.
  1397. ** RETURN: PRStatus
  1398. **     Upon successful completion of TCP socket pair, PR_NewTCPSocketPair 
  1399. **     returns PR_SUCCESS.  Otherwise, it returns PR_FAILURE.  Further
  1400. **     failure information can be obtained by calling PR_GetError().
  1401. ** XXX can we implement this on windoze and mac?
  1402. **************************************************************************
  1403. **/
  1404. PR_EXTERN(PRStatus) PR_NewTCPSocketPair(PRFileDesc *fds[2]);
  1405.  
  1406. /*
  1407. *************************************************************************
  1408. ** FUNCTION: PR_GetSockName
  1409. ** DESCRIPTION:
  1410. **    Get socket name.  Return the network address for this socket.
  1411. **
  1412. ** INPUTS:
  1413. **     PRFileDesc *fd
  1414. **       Points to a PRFileDesc object representing the socket.
  1415. ** OUTPUTS:
  1416. **     PRNetAddr *addr
  1417. **       Returns the address of the socket in its own communication space.
  1418. ** RETURN: PRStatus
  1419. **     Upon successful completion, PR_GetSockName returns PR_SUCCESS.  
  1420. **     Otherwise, it returns PR_FAILURE.  Further failure information can 
  1421. **     be obtained by calling PR_GetError().
  1422. **************************************************************************
  1423. **/
  1424. PR_EXTERN(PRStatus)    PR_GetSockName(PRFileDesc *fd, PRNetAddr *addr);
  1425.  
  1426. /*
  1427. *************************************************************************
  1428. ** FUNCTION: PR_GetPeerName
  1429. ** DESCRIPTION:
  1430. **    Get name of the connected peer.  Return the network address for the 
  1431. **    connected peer socket.
  1432. **
  1433. ** INPUTS:
  1434. **     PRFileDesc *fd
  1435. **       Points to a PRFileDesc object representing the connected peer.
  1436. ** OUTPUTS:
  1437. **     PRNetAddr *addr
  1438. **       Returns the address of the connected peer in its own communication
  1439. **       space.
  1440. ** RETURN: PRStatus
  1441. **     Upon successful completion, PR_GetPeerName returns PR_SUCCESS.  
  1442. **     Otherwise, it returns PR_FAILURE.  Further failure information can 
  1443. **     be obtained by calling PR_GetError().
  1444. **************************************************************************
  1445. **/
  1446. PR_EXTERN(PRStatus)    PR_GetPeerName(PRFileDesc *fd, PRNetAddr *addr);
  1447.  
  1448. PR_EXTERN(PRStatus)    PR_GetSocketOption(
  1449.     PRFileDesc *fd, PRSocketOptionData *data);
  1450.  
  1451. PR_EXTERN(PRStatus)    PR_SetSocketOption(
  1452.     PRFileDesc *fd, const PRSocketOptionData *data);
  1453.  
  1454. /*
  1455.  *********************************************************************
  1456.  *
  1457.  * Memory-mapped files
  1458.  *
  1459.  *********************************************************************
  1460.  */
  1461.  
  1462. typedef struct PRFileMap PRFileMap;
  1463.  
  1464. /*
  1465.  * protection options for read and write accesses of a file mapping
  1466.  */
  1467. typedef enum PRFileMapProtect {
  1468.     PR_PROT_READONLY,     /* read only */
  1469.     PR_PROT_READWRITE,    /* readable, and write is shared */
  1470.     PR_PROT_WRITECOPY     /* readable, and write is private (copy-on-write) */
  1471. } PRFileMapProtect;
  1472.  
  1473. PR_EXTERN(PRFileMap *) PR_CreateFileMap(
  1474.     PRFileDesc *fd,
  1475.     PRInt64 size,
  1476.     PRFileMapProtect prot);
  1477.  
  1478. PR_EXTERN(void *) PR_MemMap(
  1479.     PRFileMap *fmap,
  1480.     PRInt64 offset,  /* must be aligned and sized to whole pages */
  1481.     PRUint32 len);
  1482.  
  1483. PR_EXTERN(PRStatus) PR_MemUnmap(void *addr, PRUint32 len);
  1484.  
  1485. PR_EXTERN(PRStatus) PR_CloseFileMap(PRFileMap *fmap);
  1486.  
  1487. /*
  1488.  ******************************************************************
  1489.  *
  1490.  * Interprocess communication
  1491.  *
  1492.  ******************************************************************
  1493.  */
  1494.  
  1495. /*
  1496.  * Creates an anonymous pipe and returns file descriptors for the
  1497.  * read and write ends of the pipe.
  1498.  */
  1499.  
  1500. PR_EXTERN(PRStatus) PR_CreatePipe(
  1501.     PRFileDesc **readPipe,
  1502.     PRFileDesc **writePipe
  1503. );
  1504.  
  1505. /************************************************************************/
  1506. /************** The following definitions are for poll ******************/
  1507. /************************************************************************/
  1508.  
  1509. struct PRPollDesc {
  1510.     PRFileDesc* fd;
  1511.     PRInt16 in_flags;
  1512.     PRInt16 out_flags;
  1513. };
  1514.  
  1515. /*
  1516. ** Bit values for PRPollDesc.in_flags or PRPollDesc.out_flags. Binary-or
  1517. ** these together to produce the desired poll request.
  1518. **
  1519. ** On Unix platforms where we use poll() to block the idle threads,
  1520. ** the various PR_POLL_XXX flags are mapped to the native poll flags.
  1521. */
  1522.  
  1523. #if defined(XP_UNIX) && defined(_PR_USE_POLL)
  1524.  
  1525. #include <poll.h>
  1526. #define PR_POLL_READ    POLLIN
  1527. #define PR_POLL_WRITE   POLLOUT
  1528. #define PR_POLL_EXCEPT  POLLPRI
  1529. #define PR_POLL_ERR     POLLERR     /* only in out_flags */
  1530. #define PR_POLL_NVAL    POLLNVAL    /* only in out_flags when fd is bad */
  1531.  
  1532. #else  /* XP_UNIX, _PR_USE_POLL */
  1533.  
  1534. #define PR_POLL_READ    0x1
  1535. #define PR_POLL_WRITE   0x2
  1536. #define PR_POLL_EXCEPT  0x4
  1537. #define PR_POLL_ERR     0x8         /* only in out_flags */
  1538. #define PR_POLL_NVAL    0x10        /* only in out_flags when fd is bad */
  1539.  
  1540. #endif  /* XP_UNIX, _PR_USE_POLL */
  1541.  
  1542. /*
  1543. *************************************************************************
  1544. ** FUNCTION:    PR_Poll
  1545. ** DESCRIPTION:
  1546. **
  1547. ** The call returns as soon as I/O is ready on one or more of the underlying
  1548. ** file/socket objects. A count of the number of ready descriptors is
  1549. ** returned unless a timeout occurs in which case zero is returned.
  1550. **
  1551. ** PRPollDesc.in_flags should be set to the desired request
  1552. ** (read/write/except or some combination). Upon return from this call
  1553. ** PRPollDesc.out_flags will be set to indicate what kind of i/o can be
  1554. ** performed on the respective descriptor.
  1555. **
  1556. ** INPUTS:
  1557. **      PRPollDesc *pds         A pointer to an array of PRPollDesc
  1558. **
  1559. **      PRIntn npds             The number of elements in the array
  1560. **                              If this argument is zero PR_Poll is
  1561. **                              equivalent to a PR_Sleep(timeout).
  1562. **
  1563. **      PRIntervalTime timeout  Amount of time the call will block waiting
  1564. **                              for I/O to become ready. If this time expires
  1565. **                              w/o any I/O becoming ready, the result will
  1566. **                              be zero.
  1567. **
  1568. ** OUTPUTS:    None
  1569. ** RETURN:
  1570. **      PRInt32                 Number of PRPollDesc's with events or zero
  1571. **                              if the function timed out or -1 on failure.
  1572. **                              The reason for the failure is obtained by calling 
  1573. **                              PR_GetError().
  1574. ** XXX can we implement this on windoze and mac?
  1575. **************************************************************************
  1576. */
  1577. PR_EXTERN(PRInt32) PR_Poll(
  1578.     PRPollDesc *pds, PRIntn npds, PRIntervalTime timeout);
  1579.  
  1580. PR_END_EXTERN_C
  1581.  
  1582. #endif /* prio_h___ */
  1583.