andre@0: /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ andre@0: /* This Source Code Form is subject to the terms of the Mozilla Public andre@0: * License, v. 2.0. If a copy of the MPL was not distributed with this andre@0: * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ andre@0: andre@0: /* andre@0: * File: prio.h andre@0: * andre@0: * Description: PR i/o related stuff, such as file system access, file andre@0: * i/o, socket i/o, etc. andre@0: */ andre@0: andre@0: #ifndef prio_h___ andre@0: #define prio_h___ andre@0: andre@0: #include "prlong.h" andre@0: #include "prtime.h" andre@0: #include "prinrval.h" andre@0: #include "prinet.h" andre@0: andre@0: PR_BEGIN_EXTERN_C andre@0: andre@0: /* Typedefs */ andre@0: typedef struct PRDir PRDir; andre@0: typedef struct PRDirEntry PRDirEntry; andre@0: #ifdef MOZ_UNICODE andre@0: typedef struct PRDirUTF16 PRDirUTF16; andre@0: typedef struct PRDirEntryUTF16 PRDirEntryUTF16; andre@0: #endif /* MOZ_UNICODE */ andre@0: typedef struct PRFileDesc PRFileDesc; andre@0: typedef struct PRFileInfo PRFileInfo; andre@0: typedef struct PRFileInfo64 PRFileInfo64; andre@0: typedef union PRNetAddr PRNetAddr; andre@0: typedef struct PRIOMethods PRIOMethods; andre@0: typedef struct PRPollDesc PRPollDesc; andre@0: typedef struct PRFilePrivate PRFilePrivate; andre@0: typedef struct PRSendFileData PRSendFileData; andre@0: andre@0: /* andre@0: *************************************************************************** andre@0: ** The file descriptor. andre@0: ** This is the primary structure to represent any active open socket, andre@0: ** whether it be a normal file or a network connection. Such objects andre@0: ** are stackable (or layerable). Each layer may have its own set of andre@0: ** method pointers and context private to that layer. All each layer andre@0: ** knows about its neighbors is how to get to their method table. andre@0: *************************************************************************** andre@0: */ andre@0: andre@0: typedef PRIntn PRDescIdentity; /* see: Layering file descriptors */ andre@0: andre@0: struct PRFileDesc { andre@0: const PRIOMethods *methods; /* the I/O methods table */ andre@0: PRFilePrivate *secret; /* layer dependent data */ andre@0: PRFileDesc *lower, *higher; /* pointers to adjacent layers */ andre@0: void (PR_CALLBACK *dtor)(PRFileDesc *fd); andre@0: /* A destructor function for layer */ andre@0: PRDescIdentity identity; /* Identity of this particular layer */ andre@0: }; andre@0: andre@0: /* andre@0: *************************************************************************** andre@0: ** PRTransmitFileFlags andre@0: ** andre@0: ** Flags for PR_TransmitFile. Pass PR_TRANSMITFILE_CLOSE_SOCKET to andre@0: ** PR_TransmitFile if the connection should be closed after the file andre@0: ** is transmitted. andre@0: *************************************************************************** andre@0: */ andre@0: typedef enum PRTransmitFileFlags { andre@0: PR_TRANSMITFILE_KEEP_OPEN = 0, /* socket is left open after file andre@0: * is transmitted. */ andre@0: PR_TRANSMITFILE_CLOSE_SOCKET = 1 /* socket is closed after file andre@0: * is transmitted. */ andre@0: } PRTransmitFileFlags; andre@0: andre@0: /* andre@0: ************************************************************************** andre@0: ** Macros for PRNetAddr andre@0: ** andre@0: ** Address families: PR_AF_INET, PR_AF_INET6, PR_AF_LOCAL andre@0: ** IP addresses: PR_INADDR_ANY, PR_INADDR_LOOPBACK, PR_INADDR_BROADCAST andre@0: ************************************************************************** andre@0: */ andre@0: andre@0: #ifdef WIN32 andre@0: andre@0: #define PR_AF_INET 2 andre@0: #define PR_AF_LOCAL 1 andre@0: #define PR_INADDR_ANY (unsigned long)0x00000000 andre@0: #define PR_INADDR_LOOPBACK 0x7f000001 andre@0: #define PR_INADDR_BROADCAST (unsigned long)0xffffffff andre@0: andre@0: #else /* WIN32 */ andre@0: andre@0: #define PR_AF_INET AF_INET andre@0: #define PR_AF_LOCAL AF_UNIX andre@0: #define PR_INADDR_ANY INADDR_ANY andre@0: #define PR_INADDR_LOOPBACK INADDR_LOOPBACK andre@0: #define PR_INADDR_BROADCAST INADDR_BROADCAST andre@0: andre@0: #endif /* WIN32 */ andre@0: andre@0: /* andre@0: ** Define PR_AF_INET6 in prcpucfg.h with the same andre@0: ** value as AF_INET6 on platforms with IPv6 support. andre@0: ** Otherwise define it here. andre@0: */ andre@0: #ifndef PR_AF_INET6 andre@0: #define PR_AF_INET6 100 andre@0: #endif andre@0: andre@0: #define PR_AF_INET_SDP 101 andre@0: #define PR_AF_INET6_SDP 102 andre@0: andre@0: #ifndef PR_AF_UNSPEC andre@0: #define PR_AF_UNSPEC 0 andre@0: #endif andre@0: andre@0: /* andre@0: ************************************************************************** andre@0: ** A network address andre@0: ** andre@0: ** Only Internet Protocol (IPv4 and IPv6) addresses are supported. andre@0: ** The address family must always represent IPv4 (AF_INET, probably == 2) andre@0: ** or IPv6 (AF_INET6). andre@0: ************************************************************************** andre@0: *************************************************************************/ andre@0: andre@0: struct PRIPv6Addr { andre@0: union { andre@0: PRUint8 _S6_u8[16]; andre@0: PRUint16 _S6_u16[8]; andre@0: PRUint32 _S6_u32[4]; andre@0: PRUint64 _S6_u64[2]; andre@0: } _S6_un; andre@0: }; andre@0: #define pr_s6_addr _S6_un._S6_u8 andre@0: #define pr_s6_addr16 _S6_un._S6_u16 andre@0: #define pr_s6_addr32 _S6_un._S6_u32 andre@0: #define pr_s6_addr64 _S6_un._S6_u64 andre@0: andre@0: typedef struct PRIPv6Addr PRIPv6Addr; andre@0: andre@0: union PRNetAddr { andre@0: struct { andre@0: PRUint16 family; /* address family (0x00ff maskable) */ andre@0: #ifdef XP_BEOS andre@0: char data[10]; /* Be has a smaller structure */ andre@0: #else andre@0: char data[14]; /* raw address data */ andre@0: #endif andre@0: } raw; andre@0: struct { andre@0: PRUint16 family; /* address family (AF_INET) */ andre@0: PRUint16 port; /* port number */ andre@0: PRUint32 ip; /* The actual 32 bits of address */ andre@0: #ifdef XP_BEOS andre@0: char pad[4]; /* Be has a smaller structure */ andre@0: #else andre@0: char pad[8]; andre@0: #endif andre@0: } inet; andre@0: struct { andre@0: PRUint16 family; /* address family (AF_INET6) */ andre@0: PRUint16 port; /* port number */ andre@0: PRUint32 flowinfo; /* routing information */ andre@0: PRIPv6Addr ip; /* the actual 128 bits of address */ andre@0: PRUint32 scope_id; /* set of interfaces for a scope */ andre@0: } ipv6; andre@0: #if defined(XP_UNIX) || defined(XP_OS2) andre@0: struct { /* Unix domain socket address */ andre@0: PRUint16 family; /* address family (AF_UNIX) */ andre@0: #ifdef XP_OS2 andre@0: char path[108]; /* null-terminated pathname */ andre@0: /* bind fails if size is not 108. */ andre@0: #else andre@0: char path[104]; /* null-terminated pathname */ andre@0: #endif andre@0: } local; andre@0: #endif andre@0: }; andre@0: andre@0: /* andre@0: *************************************************************************** andre@0: ** PRSockOption andre@0: ** andre@0: ** The file descriptors can have predefined options set after they file andre@0: ** descriptor is created to change their behavior. Only the options in andre@0: ** the following enumeration are supported. andre@0: *************************************************************************** andre@0: */ andre@0: typedef enum PRSockOption andre@0: { andre@0: PR_SockOpt_Nonblocking, /* nonblocking io */ andre@0: PR_SockOpt_Linger, /* linger on close if data present */ andre@0: PR_SockOpt_Reuseaddr, /* allow local address reuse */ andre@0: PR_SockOpt_Keepalive, /* keep connections alive */ andre@0: PR_SockOpt_RecvBufferSize, /* send buffer size */ andre@0: PR_SockOpt_SendBufferSize, /* receive buffer size */ andre@0: andre@0: PR_SockOpt_IpTimeToLive, /* time to live */ andre@0: PR_SockOpt_IpTypeOfService, /* type of service and precedence */ andre@0: andre@0: PR_SockOpt_AddMember, /* add an IP group membership */ andre@0: PR_SockOpt_DropMember, /* drop an IP group membership */ andre@0: PR_SockOpt_McastInterface, /* multicast interface address */ andre@0: PR_SockOpt_McastTimeToLive, /* multicast timetolive */ andre@0: PR_SockOpt_McastLoopback, /* multicast loopback */ andre@0: andre@0: PR_SockOpt_NoDelay, /* don't delay send to coalesce packets */ andre@0: PR_SockOpt_MaxSegment, /* maximum segment size */ andre@0: PR_SockOpt_Broadcast, /* enable broadcast */ andre@0: PR_SockOpt_Last andre@0: } PRSockOption; andre@0: andre@0: typedef struct PRLinger { andre@0: PRBool polarity; /* Polarity of the option's setting */ andre@0: PRIntervalTime linger; /* Time to linger before closing */ andre@0: } PRLinger; andre@0: andre@0: typedef struct PRMcastRequest { andre@0: PRNetAddr mcaddr; /* IP multicast address of group */ andre@0: PRNetAddr ifaddr; /* local IP address of interface */ andre@0: } PRMcastRequest; andre@0: andre@0: typedef struct PRSocketOptionData andre@0: { andre@0: PRSockOption option; andre@0: union andre@0: { andre@0: PRUintn ip_ttl; /* IP time to live */ andre@0: PRUintn mcast_ttl; /* IP multicast time to live */ andre@0: PRUintn tos; /* IP type of service and precedence */ andre@0: PRBool non_blocking; /* Non-blocking (network) I/O */ andre@0: PRBool reuse_addr; /* Allow local address reuse */ andre@0: PRBool keep_alive; /* Keep connections alive */ andre@0: PRBool mcast_loopback; /* IP multicast loopback */ andre@0: PRBool no_delay; /* Don't delay send to coalesce packets */ andre@0: PRBool broadcast; /* Enable broadcast */ andre@0: PRSize max_segment; /* Maximum segment size */ andre@0: PRSize recv_buffer_size; /* Receive buffer size */ andre@0: PRSize send_buffer_size; /* Send buffer size */ andre@0: PRLinger linger; /* Time to linger on close if data present */ andre@0: PRMcastRequest add_member; /* add an IP group membership */ andre@0: PRMcastRequest drop_member; /* Drop an IP group membership */ andre@0: PRNetAddr mcast_if; /* multicast interface address */ andre@0: } value; andre@0: } PRSocketOptionData; andre@0: andre@0: /* andre@0: *************************************************************************** andre@0: ** PRIOVec andre@0: ** andre@0: ** The I/O vector is used by the write vector method to describe the areas andre@0: ** that are affected by the ouput operation. andre@0: *************************************************************************** andre@0: */ andre@0: typedef struct PRIOVec { andre@0: char *iov_base; andre@0: int iov_len; andre@0: } PRIOVec; andre@0: andre@0: /* andre@0: *************************************************************************** andre@0: ** Discover what type of socket is being described by the file descriptor. andre@0: *************************************************************************** andre@0: */ andre@0: typedef enum PRDescType andre@0: { andre@0: PR_DESC_FILE = 1, andre@0: PR_DESC_SOCKET_TCP = 2, andre@0: PR_DESC_SOCKET_UDP = 3, andre@0: PR_DESC_LAYERED = 4, andre@0: PR_DESC_PIPE = 5 andre@0: } PRDescType; andre@0: andre@0: typedef enum PRSeekWhence { andre@0: PR_SEEK_SET = 0, andre@0: PR_SEEK_CUR = 1, andre@0: PR_SEEK_END = 2 andre@0: } PRSeekWhence; andre@0: andre@0: NSPR_API(PRDescType) PR_GetDescType(PRFileDesc *file); andre@0: andre@0: /* andre@0: *************************************************************************** andre@0: ** PRIOMethods andre@0: ** andre@0: ** The I/O methods table provides procedural access to the functions of andre@0: ** the file descriptor. It is the responsibility of a layer implementor andre@0: ** to provide suitable functions at every entry point. If a layer provides andre@0: ** no functionality, it should call the next lower(higher) function of the andre@0: ** same name (e.g., return fd->lower->method->close(fd->lower)); andre@0: ** andre@0: ** Not all functions are implemented for all types of files. In cases where andre@0: ** that is true, the function will return a error indication with an error andre@0: ** code of PR_INVALID_METHOD_ERROR. andre@0: *************************************************************************** andre@0: */ andre@0: andre@0: typedef PRStatus (PR_CALLBACK *PRCloseFN)(PRFileDesc *fd); andre@0: typedef PRInt32 (PR_CALLBACK *PRReadFN)(PRFileDesc *fd, void *buf, PRInt32 amount); andre@0: typedef PRInt32 (PR_CALLBACK *PRWriteFN)(PRFileDesc *fd, const void *buf, PRInt32 amount); andre@0: typedef PRInt32 (PR_CALLBACK *PRAvailableFN)(PRFileDesc *fd); andre@0: typedef PRInt64 (PR_CALLBACK *PRAvailable64FN)(PRFileDesc *fd); andre@0: typedef PRStatus (PR_CALLBACK *PRFsyncFN)(PRFileDesc *fd); andre@0: typedef PROffset32 (PR_CALLBACK *PRSeekFN)(PRFileDesc *fd, PROffset32 offset, PRSeekWhence how); andre@0: typedef PROffset64 (PR_CALLBACK *PRSeek64FN)(PRFileDesc *fd, PROffset64 offset, PRSeekWhence how); andre@0: typedef PRStatus (PR_CALLBACK *PRFileInfoFN)(PRFileDesc *fd, PRFileInfo *info); andre@0: typedef PRStatus (PR_CALLBACK *PRFileInfo64FN)(PRFileDesc *fd, PRFileInfo64 *info); andre@0: typedef PRInt32 (PR_CALLBACK *PRWritevFN)( andre@0: PRFileDesc *fd, const PRIOVec *iov, PRInt32 iov_size, andre@0: PRIntervalTime timeout); andre@0: typedef PRStatus (PR_CALLBACK *PRConnectFN)( andre@0: PRFileDesc *fd, const PRNetAddr *addr, PRIntervalTime timeout); andre@0: typedef PRFileDesc* (PR_CALLBACK *PRAcceptFN) ( andre@0: PRFileDesc *fd, PRNetAddr *addr, PRIntervalTime timeout); andre@0: typedef PRStatus (PR_CALLBACK *PRBindFN)(PRFileDesc *fd, const PRNetAddr *addr); andre@0: typedef PRStatus (PR_CALLBACK *PRListenFN)(PRFileDesc *fd, PRIntn backlog); andre@0: typedef PRStatus (PR_CALLBACK *PRShutdownFN)(PRFileDesc *fd, PRIntn how); andre@0: typedef PRInt32 (PR_CALLBACK *PRRecvFN)( andre@0: PRFileDesc *fd, void *buf, PRInt32 amount, andre@0: PRIntn flags, PRIntervalTime timeout); andre@0: typedef PRInt32 (PR_CALLBACK *PRSendFN) ( andre@0: PRFileDesc *fd, const void *buf, PRInt32 amount, andre@0: PRIntn flags, PRIntervalTime timeout); andre@0: typedef PRInt32 (PR_CALLBACK *PRRecvfromFN)( andre@0: PRFileDesc *fd, void *buf, PRInt32 amount, andre@0: PRIntn flags, PRNetAddr *addr, PRIntervalTime timeout); andre@0: typedef PRInt32 (PR_CALLBACK *PRSendtoFN)( andre@0: PRFileDesc *fd, const void *buf, PRInt32 amount, andre@0: PRIntn flags, const PRNetAddr *addr, PRIntervalTime timeout); andre@0: typedef PRInt16 (PR_CALLBACK *PRPollFN)( andre@0: PRFileDesc *fd, PRInt16 in_flags, PRInt16 *out_flags); andre@0: typedef PRInt32 (PR_CALLBACK *PRAcceptreadFN)( andre@0: PRFileDesc *sd, PRFileDesc **nd, PRNetAddr **raddr, andre@0: void *buf, PRInt32 amount, PRIntervalTime t); andre@0: typedef PRInt32 (PR_CALLBACK *PRTransmitfileFN)( andre@0: PRFileDesc *sd, PRFileDesc *fd, const void *headers, andre@0: PRInt32 hlen, PRTransmitFileFlags flags, PRIntervalTime t); andre@0: typedef PRStatus (PR_CALLBACK *PRGetsocknameFN)(PRFileDesc *fd, PRNetAddr *addr); andre@0: typedef PRStatus (PR_CALLBACK *PRGetpeernameFN)(PRFileDesc *fd, PRNetAddr *addr); andre@0: typedef PRStatus (PR_CALLBACK *PRGetsocketoptionFN)( andre@0: PRFileDesc *fd, PRSocketOptionData *data); andre@0: typedef PRStatus (PR_CALLBACK *PRSetsocketoptionFN)( andre@0: PRFileDesc *fd, const PRSocketOptionData *data); andre@0: typedef PRInt32 (PR_CALLBACK *PRSendfileFN)( andre@0: PRFileDesc *networkSocket, PRSendFileData *sendData, andre@0: PRTransmitFileFlags flags, PRIntervalTime timeout); andre@0: typedef PRStatus (PR_CALLBACK *PRConnectcontinueFN)( andre@0: PRFileDesc *fd, PRInt16 out_flags); andre@0: typedef PRIntn (PR_CALLBACK *PRReservedFN)(PRFileDesc *fd); andre@0: andre@0: struct PRIOMethods { andre@0: PRDescType file_type; /* Type of file represented (tos) */ andre@0: PRCloseFN close; /* close file and destroy descriptor */ andre@0: PRReadFN read; /* read up to specified bytes into buffer */ andre@0: PRWriteFN write; /* write specified bytes from buffer */ andre@0: PRAvailableFN available; /* determine number of bytes available */ andre@0: PRAvailable64FN available64; /* ditto, 64 bit */ andre@0: PRFsyncFN fsync; /* flush all buffers to permanent store */ andre@0: PRSeekFN seek; /* position the file to the desired place */ andre@0: PRSeek64FN seek64; /* ditto, 64 bit */ andre@0: PRFileInfoFN fileInfo; /* Get information about an open file */ andre@0: PRFileInfo64FN fileInfo64; /* ditto, 64 bit */ andre@0: PRWritevFN writev; /* Write segments as described by iovector */ andre@0: PRConnectFN connect; /* Connect to the specified (net) address */ andre@0: PRAcceptFN accept; /* Accept a connection for a (net) peer */ andre@0: PRBindFN bind; /* Associate a (net) address with the fd */ andre@0: PRListenFN listen; /* Prepare to listen for (net) connections */ andre@0: PRShutdownFN shutdown; /* Shutdown a (net) connection */ andre@0: PRRecvFN recv; /* Solicit up the the specified bytes */ andre@0: PRSendFN send; /* Send all the bytes specified */ andre@0: PRRecvfromFN recvfrom; /* Solicit (net) bytes and report source */ andre@0: PRSendtoFN sendto; /* Send bytes to (net) address specified */ andre@0: PRPollFN poll; /* Test the fd to see if it is ready */ andre@0: PRAcceptreadFN acceptread; /* Accept and read on a new (net) fd */ andre@0: PRTransmitfileFN transmitfile; /* Transmit at entire file */ andre@0: PRGetsocknameFN getsockname; /* Get (net) address associated with fd */ andre@0: PRGetpeernameFN getpeername; /* Get peer's (net) address */ andre@0: PRReservedFN reserved_fn_6; /* reserved for future use */ andre@0: PRReservedFN reserved_fn_5; /* reserved for future use */ andre@0: PRGetsocketoptionFN getsocketoption; andre@0: /* Get current setting of specified option */ andre@0: PRSetsocketoptionFN setsocketoption; andre@0: /* Set value of specified option */ andre@0: PRSendfileFN sendfile; /* Send a (partial) file with header/trailer*/ andre@0: PRConnectcontinueFN connectcontinue; andre@0: /* Continue a nonblocking connect */ andre@0: PRReservedFN reserved_fn_3; /* reserved for future use */ andre@0: PRReservedFN reserved_fn_2; /* reserved for future use */ andre@0: PRReservedFN reserved_fn_1; /* reserved for future use */ andre@0: PRReservedFN reserved_fn_0; /* reserved for future use */ andre@0: }; andre@0: andre@0: /* andre@0: ************************************************************************** andre@0: * FUNCTION: PR_GetSpecialFD andre@0: * DESCRIPTION: Get the file descriptor that represents the standard input, andre@0: * output, or error stream. andre@0: * INPUTS: andre@0: * PRSpecialFD id andre@0: * A value indicating the type of stream desired: andre@0: * PR_StandardInput: standard input andre@0: * PR_StandardOuput: standard output andre@0: * PR_StandardError: standard error andre@0: * OUTPUTS: none andre@0: * RETURNS: PRFileDesc * andre@0: * If the argument is valid, PR_GetSpecialFD returns a file descriptor andre@0: * that represents the corresponding standard I/O stream. Otherwise, andre@0: * PR_GetSpecialFD returns NULL and sets error PR_INVALID_ARGUMENT_ERROR. andre@0: ************************************************************************** andre@0: */ andre@0: andre@0: typedef enum PRSpecialFD andre@0: { andre@0: PR_StandardInput, /* standard input */ andre@0: PR_StandardOutput, /* standard output */ andre@0: PR_StandardError /* standard error */ andre@0: } PRSpecialFD; andre@0: andre@0: NSPR_API(PRFileDesc*) PR_GetSpecialFD(PRSpecialFD id); andre@0: andre@0: #define PR_STDIN PR_GetSpecialFD(PR_StandardInput) andre@0: #define PR_STDOUT PR_GetSpecialFD(PR_StandardOutput) andre@0: #define PR_STDERR PR_GetSpecialFD(PR_StandardError) andre@0: andre@0: /* andre@0: ************************************************************************** andre@0: * Layering file descriptors andre@0: * andre@0: * File descriptors may be layered. Each layer has it's own identity. andre@0: * Identities are allocated by the runtime and are to be associated andre@0: * (by the layer implementor) with all layers that are of that type. andre@0: * It is then possible to scan the chain of layers and find a layer andre@0: * that one recongizes and therefore predict that it will implement andre@0: * a desired protocol. andre@0: * andre@0: * There are three well-known identities: andre@0: * PR_INVALID_IO_LAYER => an invalid layer identity, for error return andre@0: * PR_TOP_IO_LAYER => the identity of the top of the stack andre@0: * PR_NSPR_IO_LAYER => the identity used by NSPR proper andre@0: * PR_TOP_IO_LAYER may be used as a shorthand for identifying the topmost andre@0: * layer of an existing stack. Ie., the following two constructs are andre@0: * equivalent. andre@0: * andre@0: * rv = PR_PushIOLayer(stack, PR_TOP_IO_LAYER, my_layer); andre@0: * rv = PR_PushIOLayer(stack, PR_GetLayersIdentity(stack), my_layer) andre@0: * andre@0: * A string may be associated with the creation of the identity. It andre@0: * will be copied by the runtime. If queried the runtime will return andre@0: * a reference to that copied string (not yet another copy). There andre@0: * is no facility for deleting an identity. andre@0: ************************************************************************** andre@0: */ andre@0: andre@0: #define PR_IO_LAYER_HEAD (PRDescIdentity)-3 andre@0: #define PR_INVALID_IO_LAYER (PRDescIdentity)-1 andre@0: #define PR_TOP_IO_LAYER (PRDescIdentity)-2 andre@0: #define PR_NSPR_IO_LAYER (PRDescIdentity)0 andre@0: andre@0: NSPR_API(PRDescIdentity) PR_GetUniqueIdentity(const char *layer_name); andre@0: NSPR_API(const char*) PR_GetNameForIdentity(PRDescIdentity ident); andre@0: NSPR_API(PRDescIdentity) PR_GetLayersIdentity(PRFileDesc* fd); andre@0: NSPR_API(PRFileDesc*) PR_GetIdentitiesLayer(PRFileDesc* fd_stack, PRDescIdentity id); andre@0: andre@0: /* andre@0: ************************************************************************** andre@0: * PR_GetDefaultIOMethods: Accessing the default methods table. andre@0: * You may get a pointer to the default methods table by calling this function. andre@0: * You may then select any elements from that table with which to build your andre@0: * layer's methods table. You may NOT modify the table directly. andre@0: ************************************************************************** andre@0: */ andre@0: NSPR_API(const PRIOMethods *) PR_GetDefaultIOMethods(void); andre@0: andre@0: /* andre@0: ************************************************************************** andre@0: * Creating a layer andre@0: * andre@0: * A new layer may be allocated by calling PR_CreateIOLayerStub(). The andre@0: * file descriptor returned will contain the pointer to the methods table andre@0: * provided. The runtime will not modify the table nor test its correctness. andre@0: ************************************************************************** andre@0: */ andre@0: NSPR_API(PRFileDesc*) PR_CreateIOLayerStub( andre@0: PRDescIdentity ident, const PRIOMethods *methods); andre@0: andre@0: /* andre@0: ************************************************************************** andre@0: * Creating a layer andre@0: * andre@0: * A new stack may be created by calling PR_CreateIOLayer(). The andre@0: * file descriptor returned will point to the top of the stack, which has andre@0: * the layer 'fd' as the topmost layer. andre@0: * andre@0: * NOTE: This function creates a new style stack, which has a fixed, dummy andre@0: * header. The old style stack, created by a call to PR_PushIOLayer, andre@0: * results in modifying contents of the top layer of the stack, when andre@0: * pushing and popping layers of the stack. andre@0: ************************************************************************** andre@0: */ andre@0: NSPR_API(PRFileDesc*) PR_CreateIOLayer(PRFileDesc* fd); andre@0: andre@0: /* andre@0: ************************************************************************** andre@0: * Pushing a layer andre@0: * andre@0: * A file descriptor (perhaps allocated using PR_CreateIOLayerStub()) may andre@0: * be pushed into an existing stack of file descriptors at any point the andre@0: * caller deems appropriate. The new layer will be inserted into the stack andre@0: * just above the layer with the indicated identity. andre@0: * andre@0: * Note: Even if the identity parameter indicates the top-most layer of andre@0: * the stack, the value of the file descriptor describing the original andre@0: * stack will not change. andre@0: ************************************************************************** andre@0: */ andre@0: NSPR_API(PRStatus) PR_PushIOLayer( andre@0: PRFileDesc *fd_stack, PRDescIdentity id, PRFileDesc *layer); andre@0: andre@0: /* andre@0: ************************************************************************** andre@0: * Popping a layer andre@0: * andre@0: * A layer may be popped from a stack by indicating the identity of the andre@0: * layer to be removed. If found, a pointer to the removed object will andre@0: * be returned to the caller. The object then becomes the responsibility andre@0: * of the caller. andre@0: * andre@0: * Note: Even if the identity indicates the top layer of the stack, the andre@0: * reference returned will not be the file descriptor for the stack and andre@0: * that file descriptor will remain valid. andre@0: ************************************************************************** andre@0: */ andre@0: NSPR_API(PRFileDesc*) PR_PopIOLayer(PRFileDesc *fd_stack, PRDescIdentity id); andre@0: andre@0: /* andre@0: ************************************************************************** andre@0: * FUNCTION: PR_Open andre@0: * DESCRIPTION: Open a file for reading, writing, or both. andre@0: * INPUTS: andre@0: * const char *name andre@0: * The path name of the file to be opened andre@0: * PRIntn flags andre@0: * The file status flags. andre@0: * It is a bitwise OR of the following bit flags (only one of andre@0: * the first three flags below may be used): andre@0: * PR_RDONLY Open for reading only. andre@0: * PR_WRONLY Open for writing only. andre@0: * PR_RDWR Open for reading and writing. andre@0: * PR_CREATE_FILE If the file does not exist, the file is created andre@0: * If the file exists, this flag has no effect. andre@0: * PR_SYNC If set, each write will wait for both the file data andre@0: * and file status to be physically updated. andre@0: * PR_APPEND The file pointer is set to the end of andre@0: * the file prior to each write. andre@0: * PR_TRUNCATE If the file exists, its length is truncated to 0. andre@0: * PR_EXCL With PR_CREATE_FILE, if the file does not exist, andre@0: * the file is created. If the file already andre@0: * exists, no action and NULL is returned andre@0: * andre@0: * PRIntn mode andre@0: * The access permission bits of the file mode, if the file is andre@0: * created when PR_CREATE_FILE is on. andre@0: * OUTPUTS: None andre@0: * RETURNS: PRFileDesc * andre@0: * If the file is successfully opened, andre@0: * returns a pointer to the PRFileDesc andre@0: * created for the newly opened file. andre@0: * Returns a NULL pointer if the open andre@0: * failed. andre@0: * SIDE EFFECTS: andre@0: * RESTRICTIONS: andre@0: * MEMORY: andre@0: * The return value, if not NULL, points to a dynamically allocated andre@0: * PRFileDesc object. andre@0: * ALGORITHM: andre@0: ************************************************************************** andre@0: */ andre@0: andre@0: /* Open flags */ andre@0: #define PR_RDONLY 0x01 andre@0: #define PR_WRONLY 0x02 andre@0: #define PR_RDWR 0x04 andre@0: #define PR_CREATE_FILE 0x08 andre@0: #define PR_APPEND 0x10 andre@0: #define PR_TRUNCATE 0x20 andre@0: #define PR_SYNC 0x40 andre@0: #define PR_EXCL 0x80 andre@0: andre@0: /* andre@0: ** File modes .... andre@0: ** andre@0: ** CAVEAT: 'mode' is currently only applicable on UNIX platforms. andre@0: ** The 'mode' argument may be ignored by PR_Open on other platforms. andre@0: ** andre@0: ** 00400 Read by owner. andre@0: ** 00200 Write by owner. andre@0: ** 00100 Execute (search if a directory) by owner. andre@0: ** 00040 Read by group. andre@0: ** 00020 Write by group. andre@0: ** 00010 Execute by group. andre@0: ** 00004 Read by others. andre@0: ** 00002 Write by others andre@0: ** 00001 Execute by others. andre@0: ** andre@0: */ andre@0: andre@0: NSPR_API(PRFileDesc*) PR_Open(const char *name, PRIntn flags, PRIntn mode); andre@0: andre@0: /* andre@0: ************************************************************************** andre@0: * FUNCTION: PR_OpenFile andre@0: * DESCRIPTION: andre@0: * Open a file for reading, writing, or both. andre@0: * PR_OpenFile has the same prototype as PR_Open but implements andre@0: * the specified file mode where possible. andre@0: ************************************************************************** andre@0: */ andre@0: andre@0: /* File mode bits */ andre@0: #define PR_IRWXU 00700 /* read, write, execute/search by owner */ andre@0: #define PR_IRUSR 00400 /* read permission, owner */ andre@0: #define PR_IWUSR 00200 /* write permission, owner */ andre@0: #define PR_IXUSR 00100 /* execute/search permission, owner */ andre@0: #define PR_IRWXG 00070 /* read, write, execute/search by group */ andre@0: #define PR_IRGRP 00040 /* read permission, group */ andre@0: #define PR_IWGRP 00020 /* write permission, group */ andre@0: #define PR_IXGRP 00010 /* execute/search permission, group */ andre@0: #define PR_IRWXO 00007 /* read, write, execute/search by others */ andre@0: #define PR_IROTH 00004 /* read permission, others */ andre@0: #define PR_IWOTH 00002 /* write permission, others */ andre@0: #define PR_IXOTH 00001 /* execute/search permission, others */ andre@0: andre@0: NSPR_API(PRFileDesc*) PR_OpenFile( andre@0: const char *name, PRIntn flags, PRIntn mode); andre@0: andre@0: #ifdef MOZ_UNICODE andre@0: /* andre@0: * EXPERIMENTAL: This function may be removed in a future release. andre@0: */ andre@0: NSPR_API(PRFileDesc*) PR_OpenFileUTF16( andre@0: const PRUnichar *name, PRIntn flags, PRIntn mode); andre@0: #endif /* MOZ_UNICODE */ andre@0: andre@0: /* andre@0: ************************************************************************** andre@0: * FUNCTION: PR_Close andre@0: * DESCRIPTION: andre@0: * Close a file or socket. andre@0: * INPUTS: andre@0: * PRFileDesc *fd andre@0: * a pointer to a PRFileDesc. andre@0: * OUTPUTS: andre@0: * None. andre@0: * RETURN: andre@0: * PRStatus andre@0: * SIDE EFFECTS: andre@0: * RESTRICTIONS: andre@0: * None. andre@0: * MEMORY: andre@0: * The dynamic memory pointed to by the argument fd is freed. andre@0: ************************************************************************** andre@0: */ andre@0: andre@0: NSPR_API(PRStatus) PR_Close(PRFileDesc *fd); andre@0: andre@0: /* andre@0: ************************************************************************** andre@0: * FUNCTION: PR_Read andre@0: * DESCRIPTION: andre@0: * Read bytes from a file or socket. andre@0: * The operation will block until either an end of stream indication is andre@0: * encountered, some positive number of bytes are transferred, or there andre@0: * is an error. No more than 'amount' bytes will be transferred. andre@0: * INPUTS: andre@0: * PRFileDesc *fd andre@0: * pointer to the PRFileDesc object for the file or socket andre@0: * void *buf andre@0: * pointer to a buffer to hold the data read in. andre@0: * PRInt32 amount andre@0: * the size of 'buf' (in bytes) andre@0: * OUTPUTS: andre@0: * RETURN: andre@0: * PRInt32 andre@0: * a positive number indicates the number of bytes actually read in. andre@0: * 0 means end of file is reached or the network connection is closed. andre@0: * -1 indicates a failure. The reason for the failure is obtained andre@0: * by calling PR_GetError(). andre@0: * SIDE EFFECTS: andre@0: * data is written into the buffer pointed to by 'buf'. andre@0: * RESTRICTIONS: andre@0: * None. andre@0: * MEMORY: andre@0: * N/A andre@0: * ALGORITHM: andre@0: * N/A andre@0: ************************************************************************** andre@0: */ andre@0: andre@0: NSPR_API(PRInt32) PR_Read(PRFileDesc *fd, void *buf, PRInt32 amount); andre@0: andre@0: /* andre@0: *************************************************************************** andre@0: * FUNCTION: PR_Write andre@0: * DESCRIPTION: andre@0: * Write a specified number of bytes to a file or socket. The thread andre@0: * invoking this function blocks until all the data is written. andre@0: * INPUTS: andre@0: * PRFileDesc *fd andre@0: * pointer to a PRFileDesc object that refers to a file or socket andre@0: * const void *buf andre@0: * pointer to the buffer holding the data andre@0: * PRInt32 amount andre@0: * amount of data in bytes to be written from the buffer andre@0: * OUTPUTS: andre@0: * None. andre@0: * RETURN: PRInt32 andre@0: * A positive number indicates the number of bytes successfully written. andre@0: * A -1 is an indication that the operation failed. The reason andre@0: * for the failure is obtained by calling PR_GetError(). andre@0: *************************************************************************** andre@0: */ andre@0: andre@0: NSPR_API(PRInt32) PR_Write(PRFileDesc *fd,const void *buf,PRInt32 amount); andre@0: andre@0: /* andre@0: *************************************************************************** andre@0: * FUNCTION: PR_Writev andre@0: * DESCRIPTION: andre@0: * Write data to a socket. The data is organized in a PRIOVec array. The andre@0: * operation will block until all the data is written or the operation andre@0: * fails. andre@0: * INPUTS: andre@0: * PRFileDesc *fd andre@0: * Pointer that points to a PRFileDesc object for a socket. andre@0: * const PRIOVec *iov andre@0: * An array of PRIOVec. PRIOVec is a struct with the following andre@0: * two fields: andre@0: * char *iov_base; andre@0: * int iov_len; andre@0: * PRInt32 iov_size andre@0: * Number of elements in the iov array. The value of this andre@0: * argument must not be greater than PR_MAX_IOVECTOR_SIZE. andre@0: * If it is, the method will fail (PR_BUFFER_OVERFLOW_ERROR). andre@0: * PRIntervalTime timeout andre@0: * Time limit for completion of the entire write operation. andre@0: * OUTPUTS: andre@0: * None andre@0: * RETURN: andre@0: * A positive number indicates the number of bytes successfully written. andre@0: * A -1 is an indication that the operation failed. The reason andre@0: * for the failure is obtained by calling PR_GetError(). andre@0: *************************************************************************** andre@0: */ andre@0: andre@0: #define PR_MAX_IOVECTOR_SIZE 16 /* 'iov_size' must be <= */ andre@0: andre@0: NSPR_API(PRInt32) PR_Writev( andre@0: PRFileDesc *fd, const PRIOVec *iov, PRInt32 iov_size, andre@0: PRIntervalTime timeout); andre@0: andre@0: /* andre@0: *************************************************************************** andre@0: * FUNCTION: PR_Delete andre@0: * DESCRIPTION: andre@0: * Delete a file from the filesystem. The operation may fail if the andre@0: * file is open. andre@0: * INPUTS: andre@0: * const char *name andre@0: * Path name of the file to be deleted. andre@0: * OUTPUTS: andre@0: * None. andre@0: * RETURN: PRStatus andre@0: * The function returns PR_SUCCESS if the file is successfully andre@0: * deleted, otherwise it returns PR_FAILURE. andre@0: *************************************************************************** andre@0: */ andre@0: andre@0: NSPR_API(PRStatus) PR_Delete(const char *name); andre@0: andre@0: /**************************************************************************/ andre@0: andre@0: typedef enum PRFileType andre@0: { andre@0: PR_FILE_FILE = 1, andre@0: PR_FILE_DIRECTORY = 2, andre@0: PR_FILE_OTHER = 3 andre@0: } PRFileType; andre@0: andre@0: struct PRFileInfo { andre@0: PRFileType type; /* Type of file */ andre@0: PROffset32 size; /* Size, in bytes, of file's contents */ andre@0: PRTime creationTime; /* Creation time per definition of PRTime */ andre@0: PRTime modifyTime; /* Last modification time per definition of PRTime */ andre@0: }; andre@0: andre@0: struct PRFileInfo64 { andre@0: PRFileType type; /* Type of file */ andre@0: PROffset64 size; /* Size, in bytes, of file's contents */ andre@0: PRTime creationTime; /* Creation time per definition of PRTime */ andre@0: PRTime modifyTime; /* Last modification time per definition of PRTime */ andre@0: }; andre@0: andre@0: /**************************************************************************** andre@0: * FUNCTION: PR_GetFileInfo, PR_GetFileInfo64 andre@0: * DESCRIPTION: andre@0: * Get the information about the file with the given path name. This is andre@0: * applicable only to NSFileDesc describing 'file' types (see andre@0: * INPUTS: andre@0: * const char *fn andre@0: * path name of the file andre@0: * OUTPUTS: andre@0: * PRFileInfo *info andre@0: * Information about the given file is written into the file andre@0: * information object pointer to by 'info'. andre@0: * RETURN: PRStatus andre@0: * PR_GetFileInfo returns PR_SUCCESS if file information is successfully andre@0: * obtained, otherwise it returns PR_FAILURE. andre@0: *************************************************************************** andre@0: */ andre@0: andre@0: NSPR_API(PRStatus) PR_GetFileInfo(const char *fn, PRFileInfo *info); andre@0: NSPR_API(PRStatus) PR_GetFileInfo64(const char *fn, PRFileInfo64 *info); andre@0: andre@0: #ifdef MOZ_UNICODE andre@0: /* andre@0: * EXPERIMENTAL: This function may be removed in a future release. andre@0: */ andre@0: NSPR_API(PRStatus) PR_GetFileInfo64UTF16(const PRUnichar *fn, PRFileInfo64 *info); andre@0: #endif /* MOZ_UNICODE */ andre@0: andre@0: /* andre@0: ************************************************************************** andre@0: * FUNCTION: PR_GetOpenFileInfo, PR_GetOpenFileInfo64 andre@0: * DESCRIPTION: andre@0: * Get information about an open file referred to by the andre@0: * given PRFileDesc object. andre@0: * INPUTS: andre@0: * const PRFileDesc *fd andre@0: * A reference to a valid, open file. andre@0: * OUTPUTS: andre@0: * Same as PR_GetFileInfo, PR_GetFileInfo64 andre@0: * RETURN: PRStatus andre@0: * PR_GetFileInfo returns PR_SUCCESS if file information is successfully andre@0: * obtained, otherwise it returns PR_FAILURE. andre@0: *************************************************************************** andre@0: */ andre@0: andre@0: NSPR_API(PRStatus) PR_GetOpenFileInfo(PRFileDesc *fd, PRFileInfo *info); andre@0: NSPR_API(PRStatus) PR_GetOpenFileInfo64(PRFileDesc *fd, PRFileInfo64 *info); andre@0: andre@0: /* andre@0: ************************************************************************** andre@0: * FUNCTION: PR_Rename andre@0: * DESCRIPTION: andre@0: * Rename a file from the old name 'from' to the new name 'to'. andre@0: * INPUTS: andre@0: * const char *from andre@0: * The old name of the file to be renamed. andre@0: * const char *to andre@0: * The new name of the file. andre@0: * OUTPUTS: andre@0: * None. andre@0: * RETURN: PRStatus andre@0: ************************************************************************** andre@0: */ andre@0: andre@0: NSPR_API(PRStatus) PR_Rename(const char *from, const char *to); andre@0: andre@0: /* andre@0: ************************************************************************* andre@0: * FUNCTION: PR_Access andre@0: * DESCRIPTION: andre@0: * Determine accessibility of a file. andre@0: * INPUTS: andre@0: * const char *name andre@0: * path name of the file andre@0: * PRAccessHow how andre@0: * specifies which access permission to check for. andre@0: * It can be one of the following values: andre@0: * PR_ACCESS_READ_OK Test for read permission andre@0: * PR_ACCESS_WRITE_OK Test for write permission andre@0: * PR_ACCESS_EXISTS Check existence of file andre@0: * OUTPUTS: andre@0: * None. andre@0: * RETURN: PRStatus andre@0: * PR_SUCCESS is returned if the requested access is permitted. andre@0: * Otherwise, PR_FAILURE is returned. Additional information andre@0: * regarding the reason for the failure may be retrieved from andre@0: * PR_GetError(). andre@0: ************************************************************************* andre@0: */ andre@0: andre@0: typedef enum PRAccessHow { andre@0: PR_ACCESS_EXISTS = 1, andre@0: PR_ACCESS_WRITE_OK = 2, andre@0: PR_ACCESS_READ_OK = 3 andre@0: } PRAccessHow; andre@0: andre@0: NSPR_API(PRStatus) PR_Access(const char *name, PRAccessHow how); andre@0: andre@0: /* andre@0: ************************************************************************* andre@0: * FUNCTION: PR_Seek, PR_Seek64 andre@0: * DESCRIPTION: andre@0: * Moves read-write file offset andre@0: * INPUTS: andre@0: * PRFileDesc *fd andre@0: * Pointer to a PRFileDesc object. andre@0: * PROffset32, PROffset64 offset andre@0: * Specifies a value, in bytes, that is used in conjunction andre@0: * with the 'whence' parameter to set the file pointer. A andre@0: * negative value causes seeking in the reverse direction. andre@0: * PRSeekWhence whence andre@0: * Specifies how to interpret the 'offset' parameter in setting andre@0: * the file pointer associated with the 'fd' parameter. andre@0: * Values for the 'whence' parameter are: andre@0: * PR_SEEK_SET Sets the file pointer to the value of the andre@0: * 'offset' parameter andre@0: * PR_SEEK_CUR Sets the file pointer to its current location andre@0: * plus the value of the offset parameter. andre@0: * PR_SEEK_END Sets the file pointer to the size of the andre@0: * file plus the value of the offset parameter. andre@0: * OUTPUTS: andre@0: * None. andre@0: * RETURN: PROffset32, PROffset64 andre@0: * Upon successful completion, the resulting pointer location, andre@0: * measured in bytes from the beginning of the file, is returned. andre@0: * If the PR_Seek() function fails, the file offset remains andre@0: * unchanged, and the returned value is -1. The error code can andre@0: * then be retrieved via PR_GetError(). andre@0: ************************************************************************* andre@0: */ andre@0: andre@0: NSPR_API(PROffset32) PR_Seek(PRFileDesc *fd, PROffset32 offset, PRSeekWhence whence); andre@0: NSPR_API(PROffset64) PR_Seek64(PRFileDesc *fd, PROffset64 offset, PRSeekWhence whence); andre@0: andre@0: /* andre@0: ************************************************************************ andre@0: * FUNCTION: PR_Available andre@0: * DESCRIPTION: andre@0: * Determine the amount of data in bytes available for reading andre@0: * in the given file or socket. andre@0: * INPUTS: andre@0: * PRFileDesc *fd andre@0: * Pointer to a PRFileDesc object that refers to a file or andre@0: * socket. andre@0: * OUTPUTS: andre@0: * None andre@0: * RETURN: PRInt32, PRInt64 andre@0: * Upon successful completion, PR_Available returns the number of andre@0: * bytes beyond the current read pointer that is available for andre@0: * reading. Otherwise, it returns a -1 and the reason for the andre@0: * failure can be retrieved via PR_GetError(). andre@0: ************************************************************************ andre@0: */ andre@0: andre@0: NSPR_API(PRInt32) PR_Available(PRFileDesc *fd); andre@0: NSPR_API(PRInt64) PR_Available64(PRFileDesc *fd); andre@0: andre@0: /* andre@0: ************************************************************************ andre@0: * FUNCTION: PR_Sync andre@0: * DESCRIPTION: andre@0: * Sync any buffered data for a fd to its backing device (disk). andre@0: * INPUTS: andre@0: * PRFileDesc *fd andre@0: * Pointer to a PRFileDesc object that refers to a file or andre@0: * socket andre@0: * OUTPUTS: andre@0: * None andre@0: * RETURN: PRStatus andre@0: * PR_SUCCESS is returned if the requested access is permitted. andre@0: * Otherwise, PR_FAILURE is returned. andre@0: ************************************************************************ andre@0: */ andre@0: andre@0: NSPR_API(PRStatus) PR_Sync(PRFileDesc *fd); andre@0: andre@0: /************************************************************************/ andre@0: andre@0: struct PRDirEntry { andre@0: const char *name; /* name of entry, relative to directory name */ andre@0: }; andre@0: andre@0: #ifdef MOZ_UNICODE andre@0: struct PRDirEntryUTF16 { andre@0: const PRUnichar *name; /* name of entry in UTF16, relative to andre@0: * directory name */ andre@0: }; andre@0: #endif /* MOZ_UNICODE */ andre@0: andre@0: #if !defined(NO_NSPR_10_SUPPORT) andre@0: #define PR_DirName(dirEntry) (dirEntry->name) andre@0: #endif andre@0: andre@0: /* andre@0: ************************************************************************* andre@0: * FUNCTION: PR_OpenDir andre@0: * DESCRIPTION: andre@0: * Open the directory by the given name andre@0: * INPUTS: andre@0: * const char *name andre@0: * path name of the directory to be opened andre@0: * OUTPUTS: andre@0: * None andre@0: * RETURN: PRDir * andre@0: * If the directory is sucessfully opened, a PRDir object is andre@0: * dynamically allocated and a pointer to it is returned. andre@0: * If the directory cannot be opened, a NULL pointer is returned. andre@0: * MEMORY: andre@0: * Upon successful completion, the return value points to andre@0: * dynamically allocated memory. andre@0: ************************************************************************* andre@0: */ andre@0: andre@0: NSPR_API(PRDir*) PR_OpenDir(const char *name); andre@0: andre@0: #ifdef MOZ_UNICODE andre@0: /* andre@0: * EXPERIMENTAL: This function may be removed in a future release. andre@0: */ andre@0: NSPR_API(PRDirUTF16*) PR_OpenDirUTF16(const PRUnichar *name); andre@0: #endif /* MOZ_UNICODE */ andre@0: andre@0: /* andre@0: ************************************************************************* andre@0: * FUNCTION: PR_ReadDir andre@0: * DESCRIPTION: andre@0: * INPUTS: andre@0: * PRDir *dir andre@0: * pointer to a PRDir object that designates an open directory andre@0: * PRDirFlags flags andre@0: * PR_SKIP_NONE Do not skip any files andre@0: * PR_SKIP_DOT Skip the directory entry "." that andre@0: * represents the current directory andre@0: * PR_SKIP_DOT_DOT Skip the directory entry ".." that andre@0: * represents the parent directory. andre@0: * PR_SKIP_BOTH Skip both '.' and '..' andre@0: * PR_SKIP_HIDDEN Skip hidden files andre@0: * OUTPUTS: andre@0: * RETURN: PRDirEntry* andre@0: * Returns a pointer to the next entry in the directory. Returns andre@0: * a NULL pointer upon reaching the end of the directory or when an andre@0: * error occurs. The actual reason can be retrieved via PR_GetError(). andre@0: ************************************************************************* andre@0: */ andre@0: andre@0: typedef enum PRDirFlags { andre@0: PR_SKIP_NONE = 0x0, andre@0: PR_SKIP_DOT = 0x1, andre@0: PR_SKIP_DOT_DOT = 0x2, andre@0: PR_SKIP_BOTH = 0x3, andre@0: PR_SKIP_HIDDEN = 0x4 andre@0: } PRDirFlags; andre@0: andre@0: NSPR_API(PRDirEntry*) PR_ReadDir(PRDir *dir, PRDirFlags flags); andre@0: andre@0: #ifdef MOZ_UNICODE andre@0: /* andre@0: * EXPERIMENTAL: This function may be removed in a future release. andre@0: */ andre@0: NSPR_API(PRDirEntryUTF16*) PR_ReadDirUTF16(PRDirUTF16 *dir, PRDirFlags flags); andre@0: #endif /* MOZ_UNICODE */ andre@0: andre@0: /* andre@0: ************************************************************************* andre@0: * FUNCTION: PR_CloseDir andre@0: * DESCRIPTION: andre@0: * Close the specified directory. andre@0: * INPUTS: andre@0: * PRDir *dir andre@0: * The directory to be closed. andre@0: * OUTPUTS: andre@0: * None andre@0: * RETURN: PRStatus andre@0: * If successful, will return a status of PR_SUCCESS. Otherwise andre@0: * a value of PR_FAILURE. The reason for the failure may be re- andre@0: * trieved using PR_GetError(). andre@0: ************************************************************************* andre@0: */ andre@0: andre@0: NSPR_API(PRStatus) PR_CloseDir(PRDir *dir); andre@0: andre@0: #ifdef MOZ_UNICODE andre@0: /* andre@0: * EXPERIMENTAL: This function may be removed in a future release. andre@0: */ andre@0: NSPR_API(PRStatus) PR_CloseDirUTF16(PRDirUTF16 *dir); andre@0: #endif /* MOZ_UNICODE */ andre@0: andre@0: /* andre@0: ************************************************************************* andre@0: * FUNCTION: PR_MkDir andre@0: * DESCRIPTION: andre@0: * Create a new directory with the given name and access mode. andre@0: * INPUTS: andre@0: * const char *name andre@0: * The name of the directory to be created. All the path components andre@0: * up to but not including the leaf component must already exist. andre@0: * PRIntn mode andre@0: * See 'mode' definiton in PR_Open(). andre@0: * OUTPUTS: andre@0: * None andre@0: * RETURN: PRStatus andre@0: * If successful, will return a status of PR_SUCCESS. Otherwise andre@0: * a value of PR_FAILURE. The reason for the failure may be re- andre@0: * trieved using PR_GetError(). andre@0: ************************************************************************* andre@0: */ andre@0: andre@0: NSPR_API(PRStatus) PR_MkDir(const char *name, PRIntn mode); andre@0: andre@0: /* andre@0: ************************************************************************* andre@0: * FUNCTION: PR_MakeDir andre@0: * DESCRIPTION: andre@0: * Create a new directory with the given name and access mode. andre@0: * PR_MakeDir has the same prototype as PR_MkDir but implements andre@0: * the specified access mode where possible. andre@0: ************************************************************************* andre@0: */ andre@0: andre@0: NSPR_API(PRStatus) PR_MakeDir(const char *name, PRIntn mode); andre@0: andre@0: /* andre@0: ************************************************************************* andre@0: * FUNCTION: PR_RmDir andre@0: * DESCRIPTION: andre@0: * Remove a directory by the given name. andre@0: * INPUTS: andre@0: * const char *name andre@0: * The name of the directory to be removed. All the path components andre@0: * must already exist. Only the leaf component will be removed. andre@0: * OUTPUTS: andre@0: * None andre@0: * RETURN: PRStatus andre@0: * If successful, will return a status of PR_SUCCESS. Otherwise andre@0: * a value of PR_FAILURE. The reason for the failure may be re- andre@0: * trieved using PR_GetError(). andre@0: ************************************************************************** andre@0: */ andre@0: andre@0: NSPR_API(PRStatus) PR_RmDir(const char *name); andre@0: andre@0: /* andre@0: ************************************************************************* andre@0: * FUNCTION: PR_NewUDPSocket andre@0: * DESCRIPTION: andre@0: * Create a new UDP socket. andre@0: * INPUTS: andre@0: * None andre@0: * OUTPUTS: andre@0: * None andre@0: * RETURN: PRFileDesc* andre@0: * Upon successful completion, PR_NewUDPSocket returns a pointer andre@0: * to the PRFileDesc created for the newly opened UDP socket. andre@0: * Returns a NULL pointer if the creation of a new UDP socket failed. andre@0: * andre@0: ************************************************************************** andre@0: */ andre@0: andre@0: NSPR_API(PRFileDesc*) PR_NewUDPSocket(void); andre@0: andre@0: /* andre@0: ************************************************************************* andre@0: * FUNCTION: PR_NewTCPSocket andre@0: * DESCRIPTION: andre@0: * Create a new TCP socket. andre@0: * INPUTS: andre@0: * None andre@0: * OUTPUTS: andre@0: * None andre@0: * RETURN: PRFileDesc* andre@0: * Upon successful completion, PR_NewTCPSocket returns a pointer andre@0: * to the PRFileDesc created for the newly opened TCP socket. andre@0: * Returns a NULL pointer if the creation of a new TCP socket failed. andre@0: * andre@0: ************************************************************************** andre@0: */ andre@0: andre@0: NSPR_API(PRFileDesc*) PR_NewTCPSocket(void); andre@0: andre@0: /* andre@0: ************************************************************************* andre@0: * FUNCTION: PR_OpenUDPSocket andre@0: * DESCRIPTION: andre@0: * Create a new UDP socket of the specified address family. andre@0: * INPUTS: andre@0: * PRIntn af andre@0: * Address family andre@0: * OUTPUTS: andre@0: * None andre@0: * RETURN: PRFileDesc* andre@0: * Upon successful completion, PR_OpenUDPSocket returns a pointer andre@0: * to the PRFileDesc created for the newly opened UDP socket. andre@0: * Returns a NULL pointer if the creation of a new UDP socket failed. andre@0: * andre@0: ************************************************************************** andre@0: */ andre@0: andre@0: NSPR_API(PRFileDesc*) PR_OpenUDPSocket(PRIntn af); andre@0: andre@0: /* andre@0: ************************************************************************* andre@0: * FUNCTION: PR_OpenTCPSocket andre@0: * DESCRIPTION: andre@0: * Create a new TCP socket of the specified address family. andre@0: * INPUTS: andre@0: * PRIntn af andre@0: * Address family andre@0: * OUTPUTS: andre@0: * None andre@0: * RETURN: PRFileDesc* andre@0: * Upon successful completion, PR_NewTCPSocket returns a pointer andre@0: * to the PRFileDesc created for the newly opened TCP socket. andre@0: * Returns a NULL pointer if the creation of a new TCP socket failed. andre@0: * andre@0: ************************************************************************** andre@0: */ andre@0: andre@0: NSPR_API(PRFileDesc*) PR_OpenTCPSocket(PRIntn af); andre@0: andre@0: /* andre@0: ************************************************************************* andre@0: * FUNCTION: PR_Connect andre@0: * DESCRIPTION: andre@0: * Initiate a connection on a socket. andre@0: * INPUTS: andre@0: * PRFileDesc *fd andre@0: * Points to a PRFileDesc object representing a socket andre@0: * PRNetAddr *addr andre@0: * Specifies the address of the socket in its own communication andre@0: * space. andre@0: * PRIntervalTime timeout andre@0: * The function uses the lesser of the provided timeout and andre@0: * the OS's connect timeout. In particular, if you specify andre@0: * PR_INTERVAL_NO_TIMEOUT as the timeout, the OS's connection andre@0: * time limit will be used. andre@0: * andre@0: * OUTPUTS: andre@0: * None andre@0: * RETURN: PRStatus andre@0: * Upon successful completion of connection initiation, PR_Connect andre@0: * returns PR_SUCCESS. Otherwise, it returns PR_FAILURE. Further andre@0: * failure information can be obtained by calling PR_GetError(). andre@0: ************************************************************************** andre@0: */ andre@0: andre@0: NSPR_API(PRStatus) PR_Connect( andre@0: PRFileDesc *fd, const PRNetAddr *addr, PRIntervalTime timeout); andre@0: andre@0: /* andre@0: ************************************************************************* andre@0: * FUNCTION: PR_ConnectContinue andre@0: * DESCRIPTION: andre@0: * Continue a nonblocking connect. After a nonblocking connect andre@0: * is initiated with PR_Connect() (which fails with andre@0: * PR_IN_PROGRESS_ERROR), one should call PR_Poll() on the socket, andre@0: * with the in_flags PR_POLL_WRITE | PR_POLL_EXCEPT. When andre@0: * PR_Poll() returns, one calls PR_ConnectContinue() on the andre@0: * socket to determine whether the nonblocking connect has andre@0: * completed or is still in progress. Repeat the PR_Poll(), andre@0: * PR_ConnectContinue() sequence until the nonblocking connect andre@0: * has completed. andre@0: * INPUTS: andre@0: * PRFileDesc *fd andre@0: * the file descriptor representing a socket andre@0: * PRInt16 out_flags andre@0: * the out_flags field of the poll descriptor returned by andre@0: * PR_Poll() andre@0: * RETURN: PRStatus andre@0: * If the nonblocking connect has successfully completed, andre@0: * PR_ConnectContinue returns PR_SUCCESS. If PR_ConnectContinue() andre@0: * returns PR_FAILURE, call PR_GetError(): andre@0: * - PR_IN_PROGRESS_ERROR: the nonblocking connect is still in andre@0: * progress and has not completed yet. The caller should poll andre@0: * on the file descriptor for the in_flags andre@0: * PR_POLL_WRITE|PR_POLL_EXCEPT and retry PR_ConnectContinue andre@0: * later when PR_Poll() returns. andre@0: * - Other errors: the nonblocking connect has failed with this andre@0: * error code. andre@0: */ andre@0: andre@0: NSPR_API(PRStatus) PR_ConnectContinue(PRFileDesc *fd, PRInt16 out_flags); andre@0: andre@0: /* andre@0: ************************************************************************* andre@0: * THIS FUNCTION IS DEPRECATED. USE PR_ConnectContinue INSTEAD. andre@0: * andre@0: * FUNCTION: PR_GetConnectStatus andre@0: * DESCRIPTION: andre@0: * Get the completion status of a nonblocking connect. After andre@0: * a nonblocking connect is initiated with PR_Connect() (which andre@0: * fails with PR_IN_PROGRESS_ERROR), one should call PR_Poll() andre@0: * on the socket, with the in_flags PR_POLL_WRITE | PR_POLL_EXCEPT. andre@0: * When PR_Poll() returns, one calls PR_GetConnectStatus on the andre@0: * PRPollDesc structure to determine whether the nonblocking andre@0: * connect has succeeded or failed. andre@0: * INPUTS: andre@0: * const PRPollDesc *pd andre@0: * Pointer to a PRPollDesc whose fd member is the socket, andre@0: * and in_flags must contain PR_POLL_WRITE and PR_POLL_EXCEPT. andre@0: * PR_Poll() should have been called and set the out_flags. andre@0: * RETURN: PRStatus andre@0: * If the nonblocking connect has successfully completed, andre@0: * PR_GetConnectStatus returns PR_SUCCESS. If PR_GetConnectStatus() andre@0: * returns PR_FAILURE, call PR_GetError(): andre@0: * - PR_IN_PROGRESS_ERROR: the nonblocking connect is still in andre@0: * progress and has not completed yet. andre@0: * - Other errors: the nonblocking connect has failed with this andre@0: * error code. andre@0: */ andre@0: andre@0: NSPR_API(PRStatus) PR_GetConnectStatus(const PRPollDesc *pd); andre@0: andre@0: /* andre@0: ************************************************************************* andre@0: * FUNCTION: PR_Accept andre@0: * DESCRIPTION: andre@0: * Accept a connection on a socket. andre@0: * INPUTS: andre@0: * PRFileDesc *fd andre@0: * Points to a PRFileDesc object representing the rendezvous socket andre@0: * on which the caller is willing to accept new connections. andre@0: * PRIntervalTime timeout andre@0: * Time limit for completion of the accept operation. andre@0: * OUTPUTS: andre@0: * PRNetAddr *addr andre@0: * Returns the address of the connecting entity in its own andre@0: * communication space. It may be NULL. andre@0: * RETURN: PRFileDesc* andre@0: * Upon successful acceptance of a connection, PR_Accept andre@0: * returns a valid file descriptor. Otherwise, it returns NULL. andre@0: * Further failure information can be obtained by calling PR_GetError(). andre@0: ************************************************************************** andre@0: */ andre@0: andre@0: NSPR_API(PRFileDesc*) PR_Accept( andre@0: PRFileDesc *fd, PRNetAddr *addr, PRIntervalTime timeout); andre@0: andre@0: /* andre@0: ************************************************************************* andre@0: * FUNCTION: PR_Bind andre@0: * DESCRIPTION: andre@0: * Bind an address to a socket. andre@0: * INPUTS: andre@0: * PRFileDesc *fd andre@0: * Points to a PRFileDesc object representing a socket. andre@0: * PRNetAddr *addr andre@0: * Specifies the address to which the socket will be bound. andre@0: * OUTPUTS: andre@0: * None andre@0: * RETURN: PRStatus andre@0: * Upon successful binding of an address to a socket, PR_Bind andre@0: * returns PR_SUCCESS. Otherwise, it returns PR_FAILURE. Further andre@0: * failure information can be obtained by calling PR_GetError(). andre@0: ************************************************************************** andre@0: */ andre@0: andre@0: NSPR_API(PRStatus) PR_Bind(PRFileDesc *fd, const PRNetAddr *addr); andre@0: andre@0: /* andre@0: ************************************************************************* andre@0: * FUNCTION: PR_Listen andre@0: * DESCRIPTION: andre@0: * Listen for connections on a socket. andre@0: * INPUTS: andre@0: * PRFileDesc *fd andre@0: * Points to a PRFileDesc object representing a socket that will be andre@0: * used to listen for new connections. andre@0: * PRIntn backlog andre@0: * Specifies the maximum length of the queue of pending connections. andre@0: * OUTPUTS: andre@0: * None andre@0: * RETURN: PRStatus andre@0: * Upon successful completion of listen request, PR_Listen andre@0: * returns PR_SUCCESS. Otherwise, it returns PR_FAILURE. Further andre@0: * failure information can be obtained by calling PR_GetError(). andre@0: ************************************************************************** andre@0: */ andre@0: andre@0: NSPR_API(PRStatus) PR_Listen(PRFileDesc *fd, PRIntn backlog); andre@0: andre@0: /* andre@0: ************************************************************************* andre@0: * FUNCTION: PR_Shutdown andre@0: * DESCRIPTION: andre@0: * Shut down part of a full-duplex connection on a socket. andre@0: * INPUTS: andre@0: * PRFileDesc *fd andre@0: * Points to a PRFileDesc object representing a connected socket. andre@0: * PRIntn how andre@0: * Specifies the kind of disallowed operations on the socket. andre@0: * PR_SHUTDOWN_RCV - Further receives will be disallowed andre@0: * PR_SHUTDOWN_SEND - Further sends will be disallowed andre@0: * PR_SHUTDOWN_BOTH - Further sends and receives will be disallowed andre@0: * OUTPUTS: andre@0: * None andre@0: * RETURN: PRStatus andre@0: * Upon successful completion of shutdown request, PR_Shutdown andre@0: * returns PR_SUCCESS. Otherwise, it returns PR_FAILURE. Further andre@0: * failure information can be obtained by calling PR_GetError(). andre@0: ************************************************************************** andre@0: */ andre@0: andre@0: typedef enum PRShutdownHow andre@0: { andre@0: PR_SHUTDOWN_RCV = 0, /* disallow further receives */ andre@0: PR_SHUTDOWN_SEND = 1, /* disallow further sends */ andre@0: PR_SHUTDOWN_BOTH = 2 /* disallow further receives and sends */ andre@0: } PRShutdownHow; andre@0: andre@0: NSPR_API(PRStatus) PR_Shutdown(PRFileDesc *fd, PRShutdownHow how); andre@0: andre@0: /* andre@0: ************************************************************************* andre@0: * FUNCTION: PR_Recv andre@0: * DESCRIPTION: andre@0: * Receive a specified number of bytes from a connected socket. andre@0: * The operation will block until some positive number of bytes are andre@0: * transferred, a time out has occurred, or there is an error. andre@0: * No more than 'amount' bytes will be transferred. andre@0: * INPUTS: andre@0: * PRFileDesc *fd andre@0: * points to a PRFileDesc object representing a socket. andre@0: * void *buf andre@0: * pointer to a buffer to hold the data received. andre@0: * PRInt32 amount andre@0: * the size of 'buf' (in bytes) andre@0: * PRIntn flags andre@0: * must be zero or PR_MSG_PEEK. andre@0: * PRIntervalTime timeout andre@0: * Time limit for completion of the receive operation. andre@0: * OUTPUTS: andre@0: * None andre@0: * RETURN: PRInt32 andre@0: * a positive number indicates the number of bytes actually received. andre@0: * 0 means the network connection is closed. andre@0: * -1 indicates a failure. The reason for the failure is obtained andre@0: * by calling PR_GetError(). andre@0: ************************************************************************** andre@0: */ andre@0: andre@0: #define PR_MSG_PEEK 0x2 andre@0: andre@0: NSPR_API(PRInt32) PR_Recv(PRFileDesc *fd, void *buf, PRInt32 amount, andre@0: PRIntn flags, PRIntervalTime timeout); andre@0: andre@0: /* andre@0: ************************************************************************* andre@0: * FUNCTION: PR_Send andre@0: * DESCRIPTION: andre@0: * Send a specified number of bytes from a connected socket. andre@0: * The operation will block until all bytes are andre@0: * processed, a time out has occurred, or there is an error. andre@0: * INPUTS: andre@0: * PRFileDesc *fd andre@0: * points to a PRFileDesc object representing a socket. andre@0: * void *buf andre@0: * pointer to a buffer from where the data is sent. andre@0: * PRInt32 amount andre@0: * the size of 'buf' (in bytes) andre@0: * PRIntn flags andre@0: * (OBSOLETE - must always be zero) andre@0: * PRIntervalTime timeout andre@0: * Time limit for completion of the send operation. andre@0: * OUTPUTS: andre@0: * None andre@0: * RETURN: PRInt32 andre@0: * A positive number indicates the number of bytes successfully processed. andre@0: * This number must always equal 'amount'. A -1 is an indication that the andre@0: * operation failed. The reason for the failure is obtained by calling andre@0: * PR_GetError(). andre@0: ************************************************************************** andre@0: */ andre@0: andre@0: NSPR_API(PRInt32) PR_Send(PRFileDesc *fd, const void *buf, PRInt32 amount, andre@0: PRIntn flags, PRIntervalTime timeout); andre@0: andre@0: /* andre@0: ************************************************************************* andre@0: * FUNCTION: PR_RecvFrom andre@0: * DESCRIPTION: andre@0: * Receive up to a specified number of bytes from socket which may andre@0: * or may not be connected. andre@0: * The operation will block until one or more bytes are andre@0: * transferred, a time out has occurred, or there is an error. andre@0: * No more than 'amount' bytes will be transferred. andre@0: * INPUTS: andre@0: * PRFileDesc *fd andre@0: * points to a PRFileDesc object representing a socket. andre@0: * void *buf andre@0: * pointer to a buffer to hold the data received. andre@0: * PRInt32 amount andre@0: * the size of 'buf' (in bytes) andre@0: * PRIntn flags andre@0: * (OBSOLETE - must always be zero) andre@0: * PRNetAddr *addr andre@0: * Specifies the address of the sending peer. It may be NULL. andre@0: * PRIntervalTime timeout andre@0: * Time limit for completion of the receive operation. andre@0: * OUTPUTS: andre@0: * None andre@0: * RETURN: PRInt32 andre@0: * a positive number indicates the number of bytes actually received. andre@0: * 0 means the network connection is closed. andre@0: * -1 indicates a failure. The reason for the failure is obtained andre@0: * by calling PR_GetError(). andre@0: ************************************************************************** andre@0: */ andre@0: andre@0: NSPR_API(PRInt32) PR_RecvFrom( andre@0: PRFileDesc *fd, void *buf, PRInt32 amount, PRIntn flags, andre@0: PRNetAddr *addr, PRIntervalTime timeout); andre@0: andre@0: /* andre@0: ************************************************************************* andre@0: * FUNCTION: PR_SendTo andre@0: * DESCRIPTION: andre@0: * Send a specified number of bytes from an unconnected socket. andre@0: * The operation will block until all bytes are andre@0: * sent, a time out has occurred, or there is an error. andre@0: * INPUTS: andre@0: * PRFileDesc *fd andre@0: * points to a PRFileDesc object representing an unconnected socket. andre@0: * void *buf andre@0: * pointer to a buffer from where the data is sent. andre@0: * PRInt32 amount andre@0: * the size of 'buf' (in bytes) andre@0: * PRIntn flags andre@0: * (OBSOLETE - must always be zero) andre@0: * PRNetAddr *addr andre@0: * Specifies the address of the peer. andre@0: .* PRIntervalTime timeout andre@0: * Time limit for completion of the send operation. andre@0: * OUTPUTS: andre@0: * None andre@0: * RETURN: PRInt32 andre@0: * A positive number indicates the number of bytes successfully sent. andre@0: * -1 indicates a failure. The reason for the failure is obtained andre@0: * by calling PR_GetError(). andre@0: ************************************************************************** andre@0: */ andre@0: andre@0: NSPR_API(PRInt32) PR_SendTo( andre@0: PRFileDesc *fd, const void *buf, PRInt32 amount, PRIntn flags, andre@0: const PRNetAddr *addr, PRIntervalTime timeout); andre@0: andre@0: /* andre@0: ************************************************************************* andre@0: ** FUNCTION: PR_TransmitFile andre@0: ** DESCRIPTION: andre@0: ** Transmitfile sends a complete file (sourceFile) across a socket andre@0: ** (networkSocket). If headers is non-NULL, the headers will be sent across andre@0: ** the socket prior to sending the file. andre@0: ** andre@0: ** Optionally, the PR_TRANSMITFILE_CLOSE_SOCKET flag may be passed to andre@0: ** transmitfile. This flag specifies that transmitfile should close the andre@0: ** socket after sending the data. andre@0: ** andre@0: ** INPUTS: andre@0: ** PRFileDesc *networkSocket andre@0: ** The socket to send data over andre@0: ** PRFileDesc *sourceFile andre@0: ** The file to send andre@0: ** const void *headers andre@0: ** A pointer to headers to be sent before sending data andre@0: ** PRInt32 hlen andre@0: ** length of header buffers in bytes. andre@0: ** PRTransmitFileFlags flags andre@0: ** If the flags indicate that the connection should be closed, andre@0: ** it will be done immediately after transferring the file, unless andre@0: ** the operation is unsuccessful. andre@0: .* PRIntervalTime timeout andre@0: * Time limit for completion of the transmit operation. andre@0: ** andre@0: ** RETURNS: andre@0: ** Returns the number of bytes written or -1 if the operation failed. andre@0: ** If an error occurs while sending the file, the PR_TRANSMITFILE_CLOSE_ andre@0: ** SOCKET flag is ignored. The reason for the failure is obtained andre@0: ** by calling PR_GetError(). andre@0: ************************************************************************** andre@0: */ andre@0: andre@0: NSPR_API(PRInt32) PR_TransmitFile( andre@0: PRFileDesc *networkSocket, PRFileDesc *sourceFile, andre@0: const void *headers, PRInt32 hlen, PRTransmitFileFlags flags, andre@0: PRIntervalTime timeout); andre@0: andre@0: /* andre@0: ************************************************************************* andre@0: ** FUNCTION: PR_SendFile andre@0: ** DESCRIPTION: andre@0: ** PR_SendFile sends data from a file (sendData->fd) across a socket andre@0: ** (networkSocket). If specified, a header and/or trailer buffer are sent andre@0: ** before and after the file, respectively. The file offset, number of bytes andre@0: ** of file data to send, the header and trailer buffers are specified in the andre@0: ** sendData argument. andre@0: ** andre@0: ** Optionally, if the PR_TRANSMITFILE_CLOSE_SOCKET flag is passed, the andre@0: ** socket is closed after successfully sending the data. andre@0: ** andre@0: ** INPUTS: andre@0: ** PRFileDesc *networkSocket andre@0: ** The socket to send data over andre@0: ** PRSendFileData *sendData andre@0: ** Contains the FD, file offset and length, header and trailer andre@0: ** buffer specifications. andre@0: ** PRTransmitFileFlags flags andre@0: ** If the flags indicate that the connection should be closed, andre@0: ** it will be done immediately after transferring the file, unless andre@0: ** the operation is unsuccessful. andre@0: .* PRIntervalTime timeout andre@0: * Time limit for completion of the send operation. andre@0: ** andre@0: ** RETURNS: andre@0: ** Returns the number of bytes written or -1 if the operation failed. andre@0: ** If an error occurs while sending the file, the PR_TRANSMITFILE_CLOSE_ andre@0: ** SOCKET flag is ignored. The reason for the failure is obtained andre@0: ** by calling PR_GetError(). andre@0: ************************************************************************** andre@0: */ andre@0: andre@0: struct PRSendFileData { andre@0: PRFileDesc *fd; /* file to send */ andre@0: PRUint32 file_offset; /* file offset */ andre@0: PRSize file_nbytes; /* number of bytes of file data to send */ andre@0: /* if 0, send data from file_offset to */ andre@0: /* end-of-file. */ andre@0: const void *header; /* header buffer */ andre@0: PRInt32 hlen; /* header len */ andre@0: const void *trailer; /* trailer buffer */ andre@0: PRInt32 tlen; /* trailer len */ andre@0: }; andre@0: andre@0: andre@0: NSPR_API(PRInt32) PR_SendFile( andre@0: PRFileDesc *networkSocket, PRSendFileData *sendData, andre@0: PRTransmitFileFlags flags, PRIntervalTime timeout); andre@0: andre@0: /* andre@0: ************************************************************************* andre@0: ** FUNCTION: PR_AcceptRead andre@0: ** DESCRIPTION: andre@0: ** AcceptRead accepts a new connection, returns the newly created andre@0: ** socket's descriptor and also returns the connecting peer's address. andre@0: ** AcceptRead, as its name suggests, also receives the first block of data andre@0: ** sent by the peer. andre@0: ** andre@0: ** INPUTS: andre@0: ** PRFileDesc *listenSock andre@0: ** A socket descriptor that has been called with the PR_Listen() andre@0: ** function, also known as the rendezvous socket. andre@0: ** void *buf andre@0: ** A pointer to a buffer to receive data sent by the client. This andre@0: ** buffer must be large enough to receive bytes of data andre@0: ** and two PRNetAddr structures, plus an extra 32 bytes. See: andre@0: ** PR_ACCEPT_READ_BUF_OVERHEAD. andre@0: ** PRInt32 amount andre@0: ** The number of bytes of client data to receive. Does not include andre@0: ** the size of the PRNetAddr structures. If 0, no data will be read andre@0: ** from the client. andre@0: ** PRIntervalTime timeout andre@0: ** The timeout interval only applies to the read portion of the andre@0: ** operation. PR_AcceptRead will block indefinitely until the andre@0: ** connection is accepted; the read will timeout after the timeout andre@0: ** interval elapses. andre@0: ** OUTPUTS: andre@0: ** PRFileDesc **acceptedSock andre@0: ** The file descriptor for the newly connected socket. This parameter andre@0: ** will only be valid if the function return does not indicate failure. andre@0: ** PRNetAddr **peerAddr, andre@0: ** The address of the remote socket. This parameter will only be andre@0: ** valid if the function return does not indicate failure. The andre@0: ** returned address is not guaranteed to be properly aligned. andre@0: ** andre@0: ** RETURNS: andre@0: ** The number of bytes read from the client or -1 on failure. The reason andre@0: ** for the failure is obtained by calling PR_GetError(). andre@0: ************************************************************************** andre@0: **/ andre@0: /* define buffer overhead constant. Add this value to the user's andre@0: ** data length when allocating a buffer to accept data. andre@0: ** Example: andre@0: ** #define USER_DATA_SIZE 10 andre@0: ** char buf[USER_DATA_SIZE + PR_ACCEPT_READ_BUF_OVERHEAD]; andre@0: ** bytesRead = PR_AcceptRead( s, fd, &a, &p, USER_DATA_SIZE, ...); andre@0: */ andre@0: #define PR_ACCEPT_READ_BUF_OVERHEAD (32+(2*sizeof(PRNetAddr))) andre@0: andre@0: NSPR_API(PRInt32) PR_AcceptRead( andre@0: PRFileDesc *listenSock, PRFileDesc **acceptedSock, andre@0: PRNetAddr **peerAddr, void *buf, PRInt32 amount, PRIntervalTime timeout); andre@0: andre@0: /* andre@0: ************************************************************************* andre@0: ** FUNCTION: PR_NewTCPSocketPair andre@0: ** DESCRIPTION: andre@0: ** Create a new TCP socket pair. The returned descriptors can be used andre@0: ** interchangeably; they are interconnected full-duplex descriptors: data andre@0: ** written to one can be read from the other and vice-versa. andre@0: ** andre@0: ** INPUTS: andre@0: ** None andre@0: ** OUTPUTS: andre@0: ** PRFileDesc *fds[2] andre@0: ** The file descriptor pair for the newly created TCP sockets. andre@0: ** RETURN: PRStatus andre@0: ** Upon successful completion of TCP socket pair, PR_NewTCPSocketPair andre@0: ** returns PR_SUCCESS. Otherwise, it returns PR_FAILURE. Further andre@0: ** failure information can be obtained by calling PR_GetError(). andre@0: ** XXX can we implement this on windoze and mac? andre@0: ************************************************************************** andre@0: **/ andre@0: NSPR_API(PRStatus) PR_NewTCPSocketPair(PRFileDesc *fds[2]); andre@0: andre@0: /* andre@0: ************************************************************************* andre@0: ** FUNCTION: PR_GetSockName andre@0: ** DESCRIPTION: andre@0: ** Get socket name. Return the network address for this socket. andre@0: ** andre@0: ** INPUTS: andre@0: ** PRFileDesc *fd andre@0: ** Points to a PRFileDesc object representing the socket. andre@0: ** OUTPUTS: andre@0: ** PRNetAddr *addr andre@0: ** Returns the address of the socket in its own communication space. andre@0: ** RETURN: PRStatus andre@0: ** Upon successful completion, PR_GetSockName returns PR_SUCCESS. andre@0: ** Otherwise, it returns PR_FAILURE. Further failure information can andre@0: ** be obtained by calling PR_GetError(). andre@0: ************************************************************************** andre@0: **/ andre@0: NSPR_API(PRStatus) PR_GetSockName(PRFileDesc *fd, PRNetAddr *addr); andre@0: andre@0: /* andre@0: ************************************************************************* andre@0: ** FUNCTION: PR_GetPeerName andre@0: ** DESCRIPTION: andre@0: ** Get name of the connected peer. Return the network address for the andre@0: ** connected peer socket. andre@0: ** andre@0: ** INPUTS: andre@0: ** PRFileDesc *fd andre@0: ** Points to a PRFileDesc object representing the connected peer. andre@0: ** OUTPUTS: andre@0: ** PRNetAddr *addr andre@0: ** Returns the address of the connected peer in its own communication andre@0: ** space. andre@0: ** RETURN: PRStatus andre@0: ** Upon successful completion, PR_GetPeerName returns PR_SUCCESS. andre@0: ** Otherwise, it returns PR_FAILURE. Further failure information can andre@0: ** be obtained by calling PR_GetError(). andre@0: ************************************************************************** andre@0: **/ andre@0: NSPR_API(PRStatus) PR_GetPeerName(PRFileDesc *fd, PRNetAddr *addr); andre@0: andre@0: NSPR_API(PRStatus) PR_GetSocketOption( andre@0: PRFileDesc *fd, PRSocketOptionData *data); andre@0: andre@0: NSPR_API(PRStatus) PR_SetSocketOption( andre@0: PRFileDesc *fd, const PRSocketOptionData *data); andre@0: andre@0: /* andre@0: ********************************************************************* andre@0: * andre@0: * File descriptor inheritance andre@0: * andre@0: ********************************************************************* andre@0: */ andre@0: andre@0: /* andre@0: ************************************************************************ andre@0: * FUNCTION: PR_SetFDInheritable andre@0: * DESCRIPTION: andre@0: * Set the inheritance attribute of a file descriptor. andre@0: * andre@0: * INPUTS: andre@0: * PRFileDesc *fd andre@0: * Points to a PRFileDesc object. andre@0: * PRBool inheritable andre@0: * If PR_TRUE, the file descriptor fd is set to be inheritable andre@0: * by a child process. If PR_FALSE, the file descriptor is set andre@0: * to be not inheritable by a child process. andre@0: * RETURN: PRStatus andre@0: * Upon successful completion, PR_SetFDInheritable returns PR_SUCCESS. andre@0: * Otherwise, it returns PR_FAILURE. Further failure information can andre@0: * be obtained by calling PR_GetError(). andre@0: ************************************************************************* andre@0: */ andre@0: NSPR_API(PRStatus) PR_SetFDInheritable( andre@0: PRFileDesc *fd, andre@0: PRBool inheritable); andre@0: andre@0: /* andre@0: ************************************************************************ andre@0: * FUNCTION: PR_GetInheritedFD andre@0: * DESCRIPTION: andre@0: * Get an inherited file descriptor with the specified name. andre@0: * andre@0: * INPUTS: andre@0: * const char *name andre@0: * The name of the inherited file descriptor. andre@0: * RETURN: PRFileDesc * andre@0: * Upon successful completion, PR_GetInheritedFD returns the andre@0: * inherited file descriptor with the specified name. Otherwise, andre@0: * it returns NULL. Further failure information can be obtained andre@0: * by calling PR_GetError(). andre@0: ************************************************************************* andre@0: */ andre@0: NSPR_API(PRFileDesc *) PR_GetInheritedFD(const char *name); andre@0: andre@0: /* andre@0: ********************************************************************* andre@0: * andre@0: * Memory-mapped files andre@0: * andre@0: ********************************************************************* andre@0: */ andre@0: andre@0: typedef struct PRFileMap PRFileMap; andre@0: andre@0: /* andre@0: * protection options for read and write accesses of a file mapping andre@0: */ andre@0: typedef enum PRFileMapProtect { andre@0: PR_PROT_READONLY, /* read only */ andre@0: PR_PROT_READWRITE, /* readable, and write is shared */ andre@0: PR_PROT_WRITECOPY /* readable, and write is private (copy-on-write) */ andre@0: } PRFileMapProtect; andre@0: andre@0: NSPR_API(PRFileMap *) PR_CreateFileMap( andre@0: PRFileDesc *fd, andre@0: PRInt64 size, andre@0: PRFileMapProtect prot); andre@0: andre@0: /* andre@0: * return the alignment (in bytes) of the offset argument to PR_MemMap andre@0: */ andre@0: NSPR_API(PRInt32) PR_GetMemMapAlignment(void); andre@0: andre@0: NSPR_API(void *) PR_MemMap( andre@0: PRFileMap *fmap, andre@0: PROffset64 offset, /* must be aligned and sized according to the andre@0: * return value of PR_GetMemMapAlignment() */ andre@0: PRUint32 len); andre@0: andre@0: NSPR_API(PRStatus) PR_MemUnmap(void *addr, PRUint32 len); andre@0: andre@0: NSPR_API(PRStatus) PR_CloseFileMap(PRFileMap *fmap); andre@0: andre@0: /* andre@0: * Synchronously flush the given memory-mapped address range of the given open andre@0: * file to disk. The function does not return until all modified data have andre@0: * been written to disk. andre@0: * andre@0: * On some platforms, the function will call PR_Sync(fd) internally if it is andre@0: * necessary for flushing modified data to disk synchronously. andre@0: */ andre@0: NSPR_API(PRStatus) PR_SyncMemMap( andre@0: PRFileDesc *fd, andre@0: void *addr, andre@0: PRUint32 len); andre@0: andre@0: /* andre@0: ****************************************************************** andre@0: * andre@0: * Interprocess communication andre@0: * andre@0: ****************************************************************** andre@0: */ andre@0: andre@0: /* andre@0: * Creates an anonymous pipe and returns file descriptors for the andre@0: * read and write ends of the pipe. andre@0: */ andre@0: andre@0: NSPR_API(PRStatus) PR_CreatePipe( andre@0: PRFileDesc **readPipe, andre@0: PRFileDesc **writePipe andre@0: ); andre@0: andre@0: /************************************************************************/ andre@0: /************** The following definitions are for poll ******************/ andre@0: /************************************************************************/ andre@0: andre@0: struct PRPollDesc { andre@0: PRFileDesc* fd; andre@0: PRInt16 in_flags; andre@0: PRInt16 out_flags; andre@0: }; andre@0: andre@0: /* andre@0: ** Bit values for PRPollDesc.in_flags or PRPollDesc.out_flags. Binary-or andre@0: ** these together to produce the desired poll request. andre@0: */ andre@0: andre@0: #if defined(_PR_POLL_BACKCOMPAT) andre@0: andre@0: #include andre@0: #define PR_POLL_READ POLLIN andre@0: #define PR_POLL_WRITE POLLOUT andre@0: #define PR_POLL_EXCEPT POLLPRI andre@0: #define PR_POLL_ERR POLLERR /* only in out_flags */ andre@0: #define PR_POLL_NVAL POLLNVAL /* only in out_flags when fd is bad */ andre@0: #define PR_POLL_HUP POLLHUP /* only in out_flags */ andre@0: andre@0: #else /* _PR_POLL_BACKCOMPAT */ andre@0: andre@0: #define PR_POLL_READ 0x1 andre@0: #define PR_POLL_WRITE 0x2 andre@0: #define PR_POLL_EXCEPT 0x4 andre@0: #define PR_POLL_ERR 0x8 /* only in out_flags */ andre@0: #define PR_POLL_NVAL 0x10 /* only in out_flags when fd is bad */ andre@0: #define PR_POLL_HUP 0x20 /* only in out_flags */ andre@0: andre@0: #endif /* _PR_POLL_BACKCOMPAT */ andre@0: andre@0: /* andre@0: ************************************************************************* andre@0: ** FUNCTION: PR_Poll andre@0: ** DESCRIPTION: andre@0: ** andre@0: ** The call returns as soon as I/O is ready on one or more of the underlying andre@0: ** socket objects. A count of the number of ready descriptors is andre@0: ** returned unless a timeout occurs in which case zero is returned. andre@0: ** andre@0: ** PRPollDesc.fd should be set to a pointer to a PRFileDesc object andre@0: ** representing a socket. This field can be set to NULL to indicate to andre@0: ** PR_Poll that this PRFileDesc object should be ignored. andre@0: ** PRPollDesc.in_flags should be set to the desired request andre@0: ** (read/write/except or some combination). Upon successful return from andre@0: ** this call PRPollDesc.out_flags will be set to indicate what kind of andre@0: ** i/o can be performed on the respective descriptor. PR_Poll() uses the andre@0: ** out_flags fields as scratch variables during the call. If PR_Poll() andre@0: ** returns 0 or -1, the out_flags fields do not contain meaningful values andre@0: ** and must not be used. andre@0: ** andre@0: ** INPUTS: andre@0: ** PRPollDesc *pds A pointer to an array of PRPollDesc andre@0: ** andre@0: ** PRIntn npds The number of elements in the array andre@0: ** If this argument is zero PR_Poll is andre@0: ** equivalent to a PR_Sleep(timeout). andre@0: ** andre@0: ** PRIntervalTime timeout Amount of time the call will block waiting andre@0: ** for I/O to become ready. If this time expires andre@0: ** w/o any I/O becoming ready, the result will andre@0: ** be zero. andre@0: ** andre@0: ** OUTPUTS: None andre@0: ** RETURN: andre@0: ** PRInt32 Number of PRPollDesc's with events or zero andre@0: ** if the function timed out or -1 on failure. andre@0: ** The reason for the failure is obtained by andre@0: ** calling PR_GetError(). andre@0: ************************************************************************** andre@0: */ andre@0: NSPR_API(PRInt32) PR_Poll( andre@0: PRPollDesc *pds, PRIntn npds, PRIntervalTime timeout); andre@0: andre@0: /* andre@0: ************************************************************************** andre@0: ** andre@0: ** Pollable events andre@0: ** andre@0: ** A pollable event is a special kind of file descriptor. andre@0: ** The only I/O operation you can perform on a pollable event andre@0: ** is to poll it with the PR_POLL_READ flag. You can't andre@0: ** read from or write to a pollable event. andre@0: ** andre@0: ** The purpose of a pollable event is to combine event waiting andre@0: ** with I/O waiting in a single PR_Poll call. Pollable events andre@0: ** are implemented using a pipe or a pair of TCP sockets andre@0: ** connected via the loopback address, therefore setting and andre@0: ** waiting for pollable events are expensive operating system andre@0: ** calls. Do not use pollable events for general thread andre@0: ** synchronization. Use condition variables instead. andre@0: ** andre@0: ** A pollable event has two states: set and unset. Events andre@0: ** are not queued, so there is no notion of an event count. andre@0: ** A pollable event is either set or unset. andre@0: ** andre@0: ** A new pollable event is created by a PR_NewPollableEvent andre@0: ** call and is initially in the unset state. andre@0: ** andre@0: ** PR_WaitForPollableEvent blocks the calling thread until andre@0: ** the pollable event is set, and then it atomically unsets andre@0: ** the pollable event before it returns. andre@0: ** andre@0: ** To set a pollable event, call PR_SetPollableEvent. andre@0: ** andre@0: ** One can call PR_Poll with the PR_POLL_READ flag on a pollable andre@0: ** event. When the pollable event is set, PR_Poll returns with andre@0: ** the PR_POLL_READ flag set in the out_flags. andre@0: ** andre@0: ** To close a pollable event, call PR_DestroyPollableEvent andre@0: ** (not PR_Close). andre@0: ** andre@0: ************************************************************************** andre@0: */ andre@0: andre@0: NSPR_API(PRFileDesc *) PR_NewPollableEvent(void); andre@0: andre@0: NSPR_API(PRStatus) PR_DestroyPollableEvent(PRFileDesc *event); andre@0: andre@0: NSPR_API(PRStatus) PR_SetPollableEvent(PRFileDesc *event); andre@0: andre@0: NSPR_API(PRStatus) PR_WaitForPollableEvent(PRFileDesc *event); andre@0: andre@0: PR_END_EXTERN_C andre@0: andre@0: #endif /* prio_h___ */