prio.h revision 5821806d5e7f356e8fa4b058a389a808ea183019
15821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ 25821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/* 35821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * The contents of this file are subject to the Mozilla Public 45821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * License Version 1.1 (the "License"); you may not use this file 55821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * except in compliance with the License. You may obtain a copy of 65821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * the License at http://www.mozilla.org/MPL/ 75821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 85821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Software distributed under the License is distributed on an "AS 95821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or 105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * implied. See the License for the specific language governing 115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * rights and limitations under the License. 125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * The Original Code is the Netscape Portable Runtime (NSPR). 145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * The Initial Developer of the Original Code is Netscape 165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Communications Corporation. Portions created by Netscape are 175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Copyright (C) 1998-2000 Netscape Communications Corporation. All 185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Rights Reserved. 195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Contributor(s): 215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Alternatively, the contents of this file may be used under the 235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * terms of the GNU General Public License Version 2 or later (the 245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * "GPL"), in which case the provisions of the GPL are applicable 255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * instead of those above. If you wish to allow use of your 265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * version of this file only under the terms of the GPL and not to 275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * allow others to use your version of this file under the MPL, 285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * indicate your decision by deleting the provisions above and 295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * replace them with the notice and other provisions required by 305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * the GPL. If you do not delete the provisions above, a recipient 315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * may use your version of this file under either the MPL or the 325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * GPL. 335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/* 365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * File: prio.h 375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Description: PR i/o related stuff, such as file system access, file 395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * i/o, socket i/o, etc. 405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#ifndef prio_h___ 435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define prio_h___ 445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "prlong.h" 465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "prtime.h" 475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "prinrval.h" 485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "prinet.h" 495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)PR_BEGIN_EXTERN_C 515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/* Typedefs */ 535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)typedef struct PRDir PRDir; 545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)typedef struct PRDirEntry PRDirEntry; 555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#ifdef MOZ_UNICODE 565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)typedef struct PRDirUTF16 PRDirUTF16; 575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)typedef struct PRDirEntryUTF16 PRDirEntryUTF16; 585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif /* MOZ_UNICODE */ 595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)typedef struct PRFileDesc PRFileDesc; 605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)typedef struct PRFileInfo PRFileInfo; 615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)typedef struct PRFileInfo64 PRFileInfo64; 625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)typedef union PRNetAddr PRNetAddr; 635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)typedef struct PRIOMethods PRIOMethods; 645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)typedef struct PRPollDesc PRPollDesc; 655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)typedef struct PRFilePrivate PRFilePrivate; 665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)typedef struct PRSendFileData PRSendFileData; 675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/* 695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)*************************************************************************** 705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** The file descriptor. 715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** This is the primary structure to represent any active open socket, 725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** whether it be a normal file or a network connection. Such objects 735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** are stackable (or layerable). Each layer may have its own set of 745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** method pointers and context private to that layer. All each layer 755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)** knows about its neighbors is how to get to their method table. 765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)*************************************************************************** 775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)*/ 785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)typedef PRIntn PRDescIdentity; /* see: Layering file descriptors */ 805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)struct PRFileDesc { 825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const PRIOMethods *methods; /* the I/O methods table */ 835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PRFilePrivate *secret; /* layer dependent data */ 845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PRFileDesc *lower, *higher; /* pointers to adjacent layers */ 85 void (PR_CALLBACK *dtor)(PRFileDesc *fd); 86 /* A destructor function for layer */ 87 PRDescIdentity identity; /* Identity of this particular layer */ 88}; 89 90/* 91*************************************************************************** 92** PRTransmitFileFlags 93** 94** Flags for PR_TransmitFile. Pass PR_TRANSMITFILE_CLOSE_SOCKET to 95** PR_TransmitFile if the connection should be closed after the file 96** is transmitted. 97*************************************************************************** 98*/ 99typedef enum PRTransmitFileFlags { 100 PR_TRANSMITFILE_KEEP_OPEN = 0, /* socket is left open after file 101 * is transmitted. */ 102 PR_TRANSMITFILE_CLOSE_SOCKET = 1 /* socket is closed after file 103 * is transmitted. */ 104} PRTransmitFileFlags; 105 106/* 107************************************************************************** 108** Macros for PRNetAddr 109** 110** Address families: PR_AF_INET, PR_AF_INET6, PR_AF_LOCAL 111** IP addresses: PR_INADDR_ANY, PR_INADDR_LOOPBACK, PR_INADDR_BROADCAST 112************************************************************************** 113*/ 114 115#ifdef WIN32 116 117#define PR_AF_INET 2 118#define PR_AF_LOCAL 1 119#define PR_INADDR_ANY (unsigned long)0x00000000 120#define PR_INADDR_LOOPBACK 0x7f000001 121#define PR_INADDR_BROADCAST (unsigned long)0xffffffff 122 123#else /* WIN32 */ 124 125#define PR_AF_INET AF_INET 126#define PR_AF_LOCAL AF_UNIX 127#define PR_INADDR_ANY INADDR_ANY 128#define PR_INADDR_LOOPBACK INADDR_LOOPBACK 129#define PR_INADDR_BROADCAST INADDR_BROADCAST 130 131#endif /* WIN32 */ 132 133/* 134** Define PR_AF_INET6 in prcpucfg.h with the same 135** value as AF_INET6 on platforms with IPv6 support. 136** Otherwise define it here. 137*/ 138#ifndef PR_AF_INET6 139#define PR_AF_INET6 100 140#endif 141 142#ifndef PR_AF_UNSPEC 143#define PR_AF_UNSPEC 0 144#endif 145 146/* 147************************************************************************** 148** A network address 149** 150** Only Internet Protocol (IPv4 and IPv6) addresses are supported. 151** The address family must always represent IPv4 (AF_INET, probably == 2) 152** or IPv6 (AF_INET6). 153************************************************************************** 154*************************************************************************/ 155 156struct PRIPv6Addr { 157 union { 158 PRUint8 _S6_u8[16]; 159 PRUint16 _S6_u16[8]; 160 PRUint32 _S6_u32[4]; 161 PRUint64 _S6_u64[2]; 162 } _S6_un; 163}; 164#define pr_s6_addr _S6_un._S6_u8 165#define pr_s6_addr16 _S6_un._S6_u16 166#define pr_s6_addr32 _S6_un._S6_u32 167#define pr_s6_addr64 _S6_un._S6_u64 168 169typedef struct PRIPv6Addr PRIPv6Addr; 170 171union PRNetAddr { 172 struct { 173 PRUint16 family; /* address family (0x00ff maskable) */ 174#ifdef XP_BEOS 175 char data[10]; /* Be has a smaller structure */ 176#else 177 char data[14]; /* raw address data */ 178#endif 179 } raw; 180 struct { 181 PRUint16 family; /* address family (AF_INET) */ 182 PRUint16 port; /* port number */ 183 PRUint32 ip; /* The actual 32 bits of address */ 184#ifdef XP_BEOS 185 char pad[4]; /* Be has a smaller structure */ 186#else 187 char pad[8]; 188#endif 189 } inet; 190 struct { 191 PRUint16 family; /* address family (AF_INET6) */ 192 PRUint16 port; /* port number */ 193 PRUint32 flowinfo; /* routing information */ 194 PRIPv6Addr ip; /* the actual 128 bits of address */ 195 PRUint32 scope_id; /* set of interfaces for a scope */ 196 } ipv6; 197#if defined(XP_UNIX) || defined(XP_OS2) 198 struct { /* Unix domain socket address */ 199 PRUint16 family; /* address family (AF_UNIX) */ 200#ifdef XP_OS2 201 char path[108]; /* null-terminated pathname */ 202 /* bind fails if size is not 108. */ 203#else 204 char path[104]; /* null-terminated pathname */ 205#endif 206 } local; 207#endif 208}; 209 210/* 211*************************************************************************** 212** PRSockOption 213** 214** The file descriptors can have predefined options set after they file 215** descriptor is created to change their behavior. Only the options in 216** the following enumeration are supported. 217*************************************************************************** 218*/ 219typedef enum PRSockOption 220{ 221 PR_SockOpt_Nonblocking, /* nonblocking io */ 222 PR_SockOpt_Linger, /* linger on close if data present */ 223 PR_SockOpt_Reuseaddr, /* allow local address reuse */ 224 PR_SockOpt_Keepalive, /* keep connections alive */ 225 PR_SockOpt_RecvBufferSize, /* send buffer size */ 226 PR_SockOpt_SendBufferSize, /* receive buffer size */ 227 228 PR_SockOpt_IpTimeToLive, /* time to live */ 229 PR_SockOpt_IpTypeOfService, /* type of service and precedence */ 230 231 PR_SockOpt_AddMember, /* add an IP group membership */ 232 PR_SockOpt_DropMember, /* drop an IP group membership */ 233 PR_SockOpt_McastInterface, /* multicast interface address */ 234 PR_SockOpt_McastTimeToLive, /* multicast timetolive */ 235 PR_SockOpt_McastLoopback, /* multicast loopback */ 236 237 PR_SockOpt_NoDelay, /* don't delay send to coalesce packets */ 238 PR_SockOpt_MaxSegment, /* maximum segment size */ 239 PR_SockOpt_Broadcast, /* enable broadcast */ 240 PR_SockOpt_Last 241} PRSockOption; 242 243typedef struct PRLinger { 244 PRBool polarity; /* Polarity of the option's setting */ 245 PRIntervalTime linger; /* Time to linger before closing */ 246} PRLinger; 247 248typedef struct PRMcastRequest { 249 PRNetAddr mcaddr; /* IP multicast address of group */ 250 PRNetAddr ifaddr; /* local IP address of interface */ 251} PRMcastRequest; 252 253typedef struct PRSocketOptionData 254{ 255 PRSockOption option; 256 union 257 { 258 PRUintn ip_ttl; /* IP time to live */ 259 PRUintn mcast_ttl; /* IP multicast time to live */ 260 PRUintn tos; /* IP type of service and precedence */ 261 PRBool non_blocking; /* Non-blocking (network) I/O */ 262 PRBool reuse_addr; /* Allow local address reuse */ 263 PRBool keep_alive; /* Keep connections alive */ 264 PRBool mcast_loopback; /* IP multicast loopback */ 265 PRBool no_delay; /* Don't delay send to coalesce packets */ 266 PRBool broadcast; /* Enable broadcast */ 267 PRSize max_segment; /* Maximum segment size */ 268 PRSize recv_buffer_size; /* Receive buffer size */ 269 PRSize send_buffer_size; /* Send buffer size */ 270 PRLinger linger; /* Time to linger on close if data present */ 271 PRMcastRequest add_member; /* add an IP group membership */ 272 PRMcastRequest drop_member; /* Drop an IP group membership */ 273 PRNetAddr mcast_if; /* multicast interface address */ 274 } value; 275} PRSocketOptionData; 276 277/* 278*************************************************************************** 279** PRIOVec 280** 281** The I/O vector is used by the write vector method to describe the areas 282** that are affected by the ouput operation. 283*************************************************************************** 284*/ 285typedef struct PRIOVec { 286 char *iov_base; 287 int iov_len; 288} PRIOVec; 289 290/* 291*************************************************************************** 292** Discover what type of socket is being described by the file descriptor. 293*************************************************************************** 294*/ 295typedef enum PRDescType 296{ 297 PR_DESC_FILE = 1, 298 PR_DESC_SOCKET_TCP = 2, 299 PR_DESC_SOCKET_UDP = 3, 300 PR_DESC_LAYERED = 4, 301 PR_DESC_PIPE = 5 302} PRDescType; 303 304typedef enum PRSeekWhence { 305 PR_SEEK_SET = 0, 306 PR_SEEK_CUR = 1, 307 PR_SEEK_END = 2 308} PRSeekWhence; 309 310NSPR_API(PRDescType) PR_GetDescType(PRFileDesc *file); 311 312/* 313*************************************************************************** 314** PRIOMethods 315** 316** The I/O methods table provides procedural access to the functions of 317** the file descriptor. It is the responsibility of a layer implementor 318** to provide suitable functions at every entry point. If a layer provides 319** no functionality, it should call the next lower(higher) function of the 320** same name (e.g., return fd->lower->method->close(fd->lower)); 321** 322** Not all functions are implemented for all types of files. In cases where 323** that is true, the function will return a error indication with an error 324** code of PR_INVALID_METHOD_ERROR. 325*************************************************************************** 326*/ 327 328typedef PRStatus (PR_CALLBACK *PRCloseFN)(PRFileDesc *fd); 329typedef PRInt32 (PR_CALLBACK *PRReadFN)(PRFileDesc *fd, void *buf, PRInt32 amount); 330typedef PRInt32 (PR_CALLBACK *PRWriteFN)(PRFileDesc *fd, const void *buf, PRInt32 amount); 331typedef PRInt32 (PR_CALLBACK *PRAvailableFN)(PRFileDesc *fd); 332typedef PRInt64 (PR_CALLBACK *PRAvailable64FN)(PRFileDesc *fd); 333typedef PRStatus (PR_CALLBACK *PRFsyncFN)(PRFileDesc *fd); 334typedef PROffset32 (PR_CALLBACK *PRSeekFN)(PRFileDesc *fd, PROffset32 offset, PRSeekWhence how); 335typedef PROffset64 (PR_CALLBACK *PRSeek64FN)(PRFileDesc *fd, PROffset64 offset, PRSeekWhence how); 336typedef PRStatus (PR_CALLBACK *PRFileInfoFN)(PRFileDesc *fd, PRFileInfo *info); 337typedef PRStatus (PR_CALLBACK *PRFileInfo64FN)(PRFileDesc *fd, PRFileInfo64 *info); 338typedef PRInt32 (PR_CALLBACK *PRWritevFN)( 339 PRFileDesc *fd, const PRIOVec *iov, PRInt32 iov_size, 340 PRIntervalTime timeout); 341typedef PRStatus (PR_CALLBACK *PRConnectFN)( 342 PRFileDesc *fd, const PRNetAddr *addr, PRIntervalTime timeout); 343typedef PRFileDesc* (PR_CALLBACK *PRAcceptFN) ( 344 PRFileDesc *fd, PRNetAddr *addr, PRIntervalTime timeout); 345typedef PRStatus (PR_CALLBACK *PRBindFN)(PRFileDesc *fd, const PRNetAddr *addr); 346typedef PRStatus (PR_CALLBACK *PRListenFN)(PRFileDesc *fd, PRIntn backlog); 347typedef PRStatus (PR_CALLBACK *PRShutdownFN)(PRFileDesc *fd, PRIntn how); 348typedef PRInt32 (PR_CALLBACK *PRRecvFN)( 349 PRFileDesc *fd, void *buf, PRInt32 amount, 350 PRIntn flags, PRIntervalTime timeout); 351typedef PRInt32 (PR_CALLBACK *PRSendFN) ( 352 PRFileDesc *fd, const void *buf, PRInt32 amount, 353 PRIntn flags, PRIntervalTime timeout); 354typedef PRInt32 (PR_CALLBACK *PRRecvfromFN)( 355 PRFileDesc *fd, void *buf, PRInt32 amount, 356 PRIntn flags, PRNetAddr *addr, PRIntervalTime timeout); 357typedef PRInt32 (PR_CALLBACK *PRSendtoFN)( 358 PRFileDesc *fd, const void *buf, PRInt32 amount, 359 PRIntn flags, const PRNetAddr *addr, PRIntervalTime timeout); 360typedef PRInt16 (PR_CALLBACK *PRPollFN)( 361 PRFileDesc *fd, PRInt16 in_flags, PRInt16 *out_flags); 362typedef PRInt32 (PR_CALLBACK *PRAcceptreadFN)( 363 PRFileDesc *sd, PRFileDesc **nd, PRNetAddr **raddr, 364 void *buf, PRInt32 amount, PRIntervalTime t); 365typedef PRInt32 (PR_CALLBACK *PRTransmitfileFN)( 366 PRFileDesc *sd, PRFileDesc *fd, const void *headers, 367 PRInt32 hlen, PRTransmitFileFlags flags, PRIntervalTime t); 368typedef PRStatus (PR_CALLBACK *PRGetsocknameFN)(PRFileDesc *fd, PRNetAddr *addr); 369typedef PRStatus (PR_CALLBACK *PRGetpeernameFN)(PRFileDesc *fd, PRNetAddr *addr); 370typedef PRStatus (PR_CALLBACK *PRGetsocketoptionFN)( 371 PRFileDesc *fd, PRSocketOptionData *data); 372typedef PRStatus (PR_CALLBACK *PRSetsocketoptionFN)( 373 PRFileDesc *fd, const PRSocketOptionData *data); 374typedef PRInt32 (PR_CALLBACK *PRSendfileFN)( 375 PRFileDesc *networkSocket, PRSendFileData *sendData, 376 PRTransmitFileFlags flags, PRIntervalTime timeout); 377typedef PRStatus (PR_CALLBACK *PRConnectcontinueFN)( 378 PRFileDesc *fd, PRInt16 out_flags); 379typedef PRIntn (PR_CALLBACK *PRReservedFN)(PRFileDesc *fd); 380 381struct PRIOMethods { 382 PRDescType file_type; /* Type of file represented (tos) */ 383 PRCloseFN close; /* close file and destroy descriptor */ 384 PRReadFN read; /* read up to specified bytes into buffer */ 385 PRWriteFN write; /* write specified bytes from buffer */ 386 PRAvailableFN available; /* determine number of bytes available */ 387 PRAvailable64FN available64; /* ditto, 64 bit */ 388 PRFsyncFN fsync; /* flush all buffers to permanent store */ 389 PRSeekFN seek; /* position the file to the desired place */ 390 PRSeek64FN seek64; /* ditto, 64 bit */ 391 PRFileInfoFN fileInfo; /* Get information about an open file */ 392 PRFileInfo64FN fileInfo64; /* ditto, 64 bit */ 393 PRWritevFN writev; /* Write segments as described by iovector */ 394 PRConnectFN connect; /* Connect to the specified (net) address */ 395 PRAcceptFN accept; /* Accept a connection for a (net) peer */ 396 PRBindFN bind; /* Associate a (net) address with the fd */ 397 PRListenFN listen; /* Prepare to listen for (net) connections */ 398 PRShutdownFN shutdown; /* Shutdown a (net) connection */ 399 PRRecvFN recv; /* Solicit up the the specified bytes */ 400 PRSendFN send; /* Send all the bytes specified */ 401 PRRecvfromFN recvfrom; /* Solicit (net) bytes and report source */ 402 PRSendtoFN sendto; /* Send bytes to (net) address specified */ 403 PRPollFN poll; /* Test the fd to see if it is ready */ 404 PRAcceptreadFN acceptread; /* Accept and read on a new (net) fd */ 405 PRTransmitfileFN transmitfile; /* Transmit at entire file */ 406 PRGetsocknameFN getsockname; /* Get (net) address associated with fd */ 407 PRGetpeernameFN getpeername; /* Get peer's (net) address */ 408 PRReservedFN reserved_fn_6; /* reserved for future use */ 409 PRReservedFN reserved_fn_5; /* reserved for future use */ 410 PRGetsocketoptionFN getsocketoption; 411 /* Get current setting of specified option */ 412 PRSetsocketoptionFN setsocketoption; 413 /* Set value of specified option */ 414 PRSendfileFN sendfile; /* Send a (partial) file with header/trailer*/ 415 PRConnectcontinueFN connectcontinue; 416 /* Continue a nonblocking connect */ 417 PRReservedFN reserved_fn_3; /* reserved for future use */ 418 PRReservedFN reserved_fn_2; /* reserved for future use */ 419 PRReservedFN reserved_fn_1; /* reserved for future use */ 420 PRReservedFN reserved_fn_0; /* reserved for future use */ 421}; 422 423/* 424 ************************************************************************** 425 * FUNCTION: PR_GetSpecialFD 426 * DESCRIPTION: Get the file descriptor that represents the standard input, 427 * output, or error stream. 428 * INPUTS: 429 * PRSpecialFD id 430 * A value indicating the type of stream desired: 431 * PR_StandardInput: standard input 432 * PR_StandardOuput: standard output 433 * PR_StandardError: standard error 434 * OUTPUTS: none 435 * RETURNS: PRFileDesc * 436 * If the argument is valid, PR_GetSpecialFD returns a file descriptor 437 * that represents the corresponding standard I/O stream. Otherwise, 438 * PR_GetSpecialFD returns NULL and sets error PR_INVALID_ARGUMENT_ERROR. 439 ************************************************************************** 440 */ 441 442typedef enum PRSpecialFD 443{ 444 PR_StandardInput, /* standard input */ 445 PR_StandardOutput, /* standard output */ 446 PR_StandardError /* standard error */ 447} PRSpecialFD; 448 449NSPR_API(PRFileDesc*) PR_GetSpecialFD(PRSpecialFD id); 450 451#define PR_STDIN PR_GetSpecialFD(PR_StandardInput) 452#define PR_STDOUT PR_GetSpecialFD(PR_StandardOutput) 453#define PR_STDERR PR_GetSpecialFD(PR_StandardError) 454 455/* 456 ************************************************************************** 457 * Layering file descriptors 458 * 459 * File descriptors may be layered. Each layer has it's own identity. 460 * Identities are allocated by the runtime and are to be associated 461 * (by the layer implementor) with all layers that are of that type. 462 * It is then possible to scan the chain of layers and find a layer 463 * that one recongizes and therefore predict that it will implement 464 * a desired protocol. 465 * 466 * There are three well-known identities: 467 * PR_INVALID_IO_LAYER => an invalid layer identity, for error return 468 * PR_TOP_IO_LAYER => the identity of the top of the stack 469 * PR_NSPR_IO_LAYER => the identity used by NSPR proper 470 * PR_TOP_IO_LAYER may be used as a shorthand for identifying the topmost 471 * layer of an existing stack. Ie., the following two constructs are 472 * equivalent. 473 * 474 * rv = PR_PushIOLayer(stack, PR_TOP_IO_LAYER, my_layer); 475 * rv = PR_PushIOLayer(stack, PR_GetLayersIdentity(stack), my_layer) 476 * 477 * A string may be associated with the creation of the identity. It 478 * will be copied by the runtime. If queried the runtime will return 479 * a reference to that copied string (not yet another copy). There 480 * is no facility for deleting an identity. 481 ************************************************************************** 482 */ 483 484#define PR_IO_LAYER_HEAD (PRDescIdentity)-3 485#define PR_INVALID_IO_LAYER (PRDescIdentity)-1 486#define PR_TOP_IO_LAYER (PRDescIdentity)-2 487#define PR_NSPR_IO_LAYER (PRDescIdentity)0 488 489NSPR_API(PRDescIdentity) PR_GetUniqueIdentity(const char *layer_name); 490NSPR_API(const char*) PR_GetNameForIdentity(PRDescIdentity ident); 491NSPR_API(PRDescIdentity) PR_GetLayersIdentity(PRFileDesc* fd); 492NSPR_API(PRFileDesc*) PR_GetIdentitiesLayer(PRFileDesc* fd_stack, PRDescIdentity id); 493 494/* 495 ************************************************************************** 496 * PR_GetDefaultIOMethods: Accessing the default methods table. 497 * You may get a pointer to the default methods table by calling this function. 498 * You may then select any elements from that table with which to build your 499 * layer's methods table. You may NOT modify the table directly. 500 ************************************************************************** 501 */ 502NSPR_API(const PRIOMethods *) PR_GetDefaultIOMethods(void); 503 504/* 505 ************************************************************************** 506 * Creating a layer 507 * 508 * A new layer may be allocated by calling PR_CreateIOLayerStub(). The 509 * file descriptor returned will contain the pointer to the methods table 510 * provided. The runtime will not modify the table nor test its correctness. 511 ************************************************************************** 512 */ 513NSPR_API(PRFileDesc*) PR_CreateIOLayerStub( 514 PRDescIdentity ident, const PRIOMethods *methods); 515 516/* 517 ************************************************************************** 518 * Creating a layer 519 * 520 * A new stack may be created by calling PR_CreateIOLayer(). The 521 * file descriptor returned will point to the top of the stack, which has 522 * the layer 'fd' as the topmost layer. 523 * 524 * NOTE: This function creates a new style stack, which has a fixed, dummy 525 * header. The old style stack, created by a call to PR_PushIOLayer, 526 * results in modifying contents of the top layer of the stack, when 527 * pushing and popping layers of the stack. 528 ************************************************************************** 529 */ 530NSPR_API(PRFileDesc*) PR_CreateIOLayer(PRFileDesc* fd); 531 532/* 533 ************************************************************************** 534 * Pushing a layer 535 * 536 * A file descriptor (perhaps allocated using PR_CreateIOLayerStub()) may 537 * be pushed into an existing stack of file descriptors at any point the 538 * caller deems appropriate. The new layer will be inserted into the stack 539 * just above the layer with the indicated identity. 540 * 541 * Note: Even if the identity parameter indicates the top-most layer of 542 * the stack, the value of the file descriptor describing the original 543 * stack will not change. 544 ************************************************************************** 545 */ 546NSPR_API(PRStatus) PR_PushIOLayer( 547 PRFileDesc *fd_stack, PRDescIdentity id, PRFileDesc *layer); 548 549/* 550 ************************************************************************** 551 * Popping a layer 552 * 553 * A layer may be popped from a stack by indicating the identity of the 554 * layer to be removed. If found, a pointer to the removed object will 555 * be returned to the caller. The object then becomes the responsibility 556 * of the caller. 557 * 558 * Note: Even if the identity indicates the top layer of the stack, the 559 * reference returned will not be the file descriptor for the stack and 560 * that file descriptor will remain valid. 561 ************************************************************************** 562 */ 563NSPR_API(PRFileDesc*) PR_PopIOLayer(PRFileDesc *fd_stack, PRDescIdentity id); 564 565/* 566 ************************************************************************** 567 * FUNCTION: PR_Open 568 * DESCRIPTION: Open a file for reading, writing, or both. 569 * INPUTS: 570 * const char *name 571 * The path name of the file to be opened 572 * PRIntn flags 573 * The file status flags. 574 * It is a bitwise OR of the following bit flags (only one of 575 * the first three flags below may be used): 576 * PR_RDONLY Open for reading only. 577 * PR_WRONLY Open for writing only. 578 * PR_RDWR Open for reading and writing. 579 * PR_CREATE_FILE If the file does not exist, the file is created 580 * If the file exists, this flag has no effect. 581 * PR_SYNC If set, each write will wait for both the file data 582 * and file status to be physically updated. 583 * PR_APPEND The file pointer is set to the end of 584 * the file prior to each write. 585 * PR_TRUNCATE If the file exists, its length is truncated to 0. 586 * PR_EXCL With PR_CREATE_FILE, if the file does not exist, 587 * the file is created. If the file already 588 * exists, no action and NULL is returned 589 * 590 * PRIntn mode 591 * The access permission bits of the file mode, if the file is 592 * created when PR_CREATE_FILE is on. 593 * OUTPUTS: None 594 * RETURNS: PRFileDesc * 595 * If the file is successfully opened, 596 * returns a pointer to the PRFileDesc 597 * created for the newly opened file. 598 * Returns a NULL pointer if the open 599 * failed. 600 * SIDE EFFECTS: 601 * RESTRICTIONS: 602 * MEMORY: 603 * The return value, if not NULL, points to a dynamically allocated 604 * PRFileDesc object. 605 * ALGORITHM: 606 ************************************************************************** 607 */ 608 609/* Open flags */ 610#define PR_RDONLY 0x01 611#define PR_WRONLY 0x02 612#define PR_RDWR 0x04 613#define PR_CREATE_FILE 0x08 614#define PR_APPEND 0x10 615#define PR_TRUNCATE 0x20 616#define PR_SYNC 0x40 617#define PR_EXCL 0x80 618 619/* 620** File modes .... 621** 622** CAVEAT: 'mode' is currently only applicable on UNIX platforms. 623** The 'mode' argument may be ignored by PR_Open on other platforms. 624** 625** 00400 Read by owner. 626** 00200 Write by owner. 627** 00100 Execute (search if a directory) by owner. 628** 00040 Read by group. 629** 00020 Write by group. 630** 00010 Execute by group. 631** 00004 Read by others. 632** 00002 Write by others 633** 00001 Execute by others. 634** 635*/ 636 637NSPR_API(PRFileDesc*) PR_Open(const char *name, PRIntn flags, PRIntn mode); 638 639/* 640 ************************************************************************** 641 * FUNCTION: PR_OpenFile 642 * DESCRIPTION: 643 * Open a file for reading, writing, or both. 644 * PR_OpenFile has the same prototype as PR_Open but implements 645 * the specified file mode where possible. 646 ************************************************************************** 647 */ 648 649/* File mode bits */ 650#define PR_IRWXU 00700 /* read, write, execute/search by owner */ 651#define PR_IRUSR 00400 /* read permission, owner */ 652#define PR_IWUSR 00200 /* write permission, owner */ 653#define PR_IXUSR 00100 /* execute/search permission, owner */ 654#define PR_IRWXG 00070 /* read, write, execute/search by group */ 655#define PR_IRGRP 00040 /* read permission, group */ 656#define PR_IWGRP 00020 /* write permission, group */ 657#define PR_IXGRP 00010 /* execute/search permission, group */ 658#define PR_IRWXO 00007 /* read, write, execute/search by others */ 659#define PR_IROTH 00004 /* read permission, others */ 660#define PR_IWOTH 00002 /* write permission, others */ 661#define PR_IXOTH 00001 /* execute/search permission, others */ 662 663NSPR_API(PRFileDesc*) PR_OpenFile( 664 const char *name, PRIntn flags, PRIntn mode); 665 666#ifdef MOZ_UNICODE 667/* 668 * EXPERIMENTAL: This function may be removed in a future release. 669 */ 670NSPR_API(PRFileDesc*) PR_OpenFileUTF16( 671 const PRUnichar *name, PRIntn flags, PRIntn mode); 672#endif /* MOZ_UNICODE */ 673 674/* 675 ************************************************************************** 676 * FUNCTION: PR_Close 677 * DESCRIPTION: 678 * Close a file or socket. 679 * INPUTS: 680 * PRFileDesc *fd 681 * a pointer to a PRFileDesc. 682 * OUTPUTS: 683 * None. 684 * RETURN: 685 * PRStatus 686 * SIDE EFFECTS: 687 * RESTRICTIONS: 688 * None. 689 * MEMORY: 690 * The dynamic memory pointed to by the argument fd is freed. 691 ************************************************************************** 692 */ 693 694NSPR_API(PRStatus) PR_Close(PRFileDesc *fd); 695 696/* 697 ************************************************************************** 698 * FUNCTION: PR_Read 699 * DESCRIPTION: 700 * Read bytes from a file or socket. 701 * The operation will block until either an end of stream indication is 702 * encountered, some positive number of bytes are transferred, or there 703 * is an error. No more than 'amount' bytes will be transferred. 704 * INPUTS: 705 * PRFileDesc *fd 706 * pointer to the PRFileDesc object for the file or socket 707 * void *buf 708 * pointer to a buffer to hold the data read in. 709 * PRInt32 amount 710 * the size of 'buf' (in bytes) 711 * OUTPUTS: 712 * RETURN: 713 * PRInt32 714 * a positive number indicates the number of bytes actually read in. 715 * 0 means end of file is reached or the network connection is closed. 716 * -1 indicates a failure. The reason for the failure is obtained 717 * by calling PR_GetError(). 718 * SIDE EFFECTS: 719 * data is written into the buffer pointed to by 'buf'. 720 * RESTRICTIONS: 721 * None. 722 * MEMORY: 723 * N/A 724 * ALGORITHM: 725 * N/A 726 ************************************************************************** 727 */ 728 729NSPR_API(PRInt32) PR_Read(PRFileDesc *fd, void *buf, PRInt32 amount); 730 731/* 732 *************************************************************************** 733 * FUNCTION: PR_Write 734 * DESCRIPTION: 735 * Write a specified number of bytes to a file or socket. The thread 736 * invoking this function blocks until all the data is written. 737 * INPUTS: 738 * PRFileDesc *fd 739 * pointer to a PRFileDesc object that refers to a file or socket 740 * const void *buf 741 * pointer to the buffer holding the data 742 * PRInt32 amount 743 * amount of data in bytes to be written from the buffer 744 * OUTPUTS: 745 * None. 746 * RETURN: PRInt32 747 * A positive number indicates the number of bytes successfully written. 748 * A -1 is an indication that the operation failed. The reason 749 * for the failure is obtained by calling PR_GetError(). 750 *************************************************************************** 751 */ 752 753NSPR_API(PRInt32) PR_Write(PRFileDesc *fd,const void *buf,PRInt32 amount); 754 755/* 756 *************************************************************************** 757 * FUNCTION: PR_Writev 758 * DESCRIPTION: 759 * Write data to a socket. The data is organized in a PRIOVec array. The 760 * operation will block until all the data is written or the operation 761 * fails. 762 * INPUTS: 763 * PRFileDesc *fd 764 * Pointer that points to a PRFileDesc object for a socket. 765 * const PRIOVec *iov 766 * An array of PRIOVec. PRIOVec is a struct with the following 767 * two fields: 768 * char *iov_base; 769 * int iov_len; 770 * PRInt32 iov_size 771 * Number of elements in the iov array. The value of this 772 * argument must not be greater than PR_MAX_IOVECTOR_SIZE. 773 * If it is, the method will fail (PR_BUFFER_OVERFLOW_ERROR). 774 * PRIntervalTime timeout 775 * Time limit for completion of the entire write operation. 776 * OUTPUTS: 777 * None 778 * RETURN: 779 * A positive number indicates the number of bytes successfully written. 780 * A -1 is an indication that the operation failed. The reason 781 * for the failure is obtained by calling PR_GetError(). 782 *************************************************************************** 783 */ 784 785#define PR_MAX_IOVECTOR_SIZE 16 /* 'iov_size' must be <= */ 786 787NSPR_API(PRInt32) PR_Writev( 788 PRFileDesc *fd, const PRIOVec *iov, PRInt32 iov_size, 789 PRIntervalTime timeout); 790 791/* 792 *************************************************************************** 793 * FUNCTION: PR_Delete 794 * DESCRIPTION: 795 * Delete a file from the filesystem. The operation may fail if the 796 * file is open. 797 * INPUTS: 798 * const char *name 799 * Path name of the file to be deleted. 800 * OUTPUTS: 801 * None. 802 * RETURN: PRStatus 803 * The function returns PR_SUCCESS if the file is successfully 804 * deleted, otherwise it returns PR_FAILURE. 805 *************************************************************************** 806 */ 807 808NSPR_API(PRStatus) PR_Delete(const char *name); 809 810/**************************************************************************/ 811 812typedef enum PRFileType 813{ 814 PR_FILE_FILE = 1, 815 PR_FILE_DIRECTORY = 2, 816 PR_FILE_OTHER = 3 817} PRFileType; 818 819struct PRFileInfo { 820 PRFileType type; /* Type of file */ 821 PROffset32 size; /* Size, in bytes, of file's contents */ 822 PRTime creationTime; /* Creation time per definition of PRTime */ 823 PRTime modifyTime; /* Last modification time per definition of PRTime */ 824}; 825 826struct PRFileInfo64 { 827 PRFileType type; /* Type of file */ 828 PROffset64 size; /* Size, in bytes, of file's contents */ 829 PRTime creationTime; /* Creation time per definition of PRTime */ 830 PRTime modifyTime; /* Last modification time per definition of PRTime */ 831}; 832 833/**************************************************************************** 834 * FUNCTION: PR_GetFileInfo, PR_GetFileInfo64 835 * DESCRIPTION: 836 * Get the information about the file with the given path name. This is 837 * applicable only to NSFileDesc describing 'file' types (see 838 * INPUTS: 839 * const char *fn 840 * path name of the file 841 * OUTPUTS: 842 * PRFileInfo *info 843 * Information about the given file is written into the file 844 * information object pointer to by 'info'. 845 * RETURN: PRStatus 846 * PR_GetFileInfo returns PR_SUCCESS if file information is successfully 847 * obtained, otherwise it returns PR_FAILURE. 848 *************************************************************************** 849 */ 850 851NSPR_API(PRStatus) PR_GetFileInfo(const char *fn, PRFileInfo *info); 852NSPR_API(PRStatus) PR_GetFileInfo64(const char *fn, PRFileInfo64 *info); 853 854#ifdef MOZ_UNICODE 855/* 856 * EXPERIMENTAL: This function may be removed in a future release. 857 */ 858NSPR_API(PRStatus) PR_GetFileInfo64UTF16(const PRUnichar *fn, PRFileInfo64 *info); 859#endif /* MOZ_UNICODE */ 860 861/* 862 ************************************************************************** 863 * FUNCTION: PR_GetOpenFileInfo, PR_GetOpenFileInfo64 864 * DESCRIPTION: 865 * Get information about an open file referred to by the 866 * given PRFileDesc object. 867 * INPUTS: 868 * const PRFileDesc *fd 869 * A reference to a valid, open file. 870 * OUTPUTS: 871 * Same as PR_GetFileInfo, PR_GetFileInfo64 872 * RETURN: PRStatus 873 * PR_GetFileInfo returns PR_SUCCESS if file information is successfully 874 * obtained, otherwise it returns PR_FAILURE. 875 *************************************************************************** 876 */ 877 878NSPR_API(PRStatus) PR_GetOpenFileInfo(PRFileDesc *fd, PRFileInfo *info); 879NSPR_API(PRStatus) PR_GetOpenFileInfo64(PRFileDesc *fd, PRFileInfo64 *info); 880 881/* 882 ************************************************************************** 883 * FUNCTION: PR_Rename 884 * DESCRIPTION: 885 * Rename a file from the old name 'from' to the new name 'to'. 886 * INPUTS: 887 * const char *from 888 * The old name of the file to be renamed. 889 * const char *to 890 * The new name of the file. 891 * OUTPUTS: 892 * None. 893 * RETURN: PRStatus 894 ************************************************************************** 895 */ 896 897NSPR_API(PRStatus) PR_Rename(const char *from, const char *to); 898 899/* 900 ************************************************************************* 901 * FUNCTION: PR_Access 902 * DESCRIPTION: 903 * Determine accessibility of a file. 904 * INPUTS: 905 * const char *name 906 * path name of the file 907 * PRAccessHow how 908 * specifies which access permission to check for. 909 * It can be one of the following values: 910 * PR_ACCESS_READ_OK Test for read permission 911 * PR_ACCESS_WRITE_OK Test for write permission 912 * PR_ACCESS_EXISTS Check existence of file 913 * OUTPUTS: 914 * None. 915 * RETURN: PRStatus 916 * PR_SUCCESS is returned if the requested access is permitted. 917 * Otherwise, PR_FAILURE is returned. Additional information 918 * regarding the reason for the failure may be retrieved from 919 * PR_GetError(). 920 ************************************************************************* 921 */ 922 923typedef enum PRAccessHow { 924 PR_ACCESS_EXISTS = 1, 925 PR_ACCESS_WRITE_OK = 2, 926 PR_ACCESS_READ_OK = 3 927} PRAccessHow; 928 929NSPR_API(PRStatus) PR_Access(const char *name, PRAccessHow how); 930 931/* 932 ************************************************************************* 933 * FUNCTION: PR_Seek, PR_Seek64 934 * DESCRIPTION: 935 * Moves read-write file offset 936 * INPUTS: 937 * PRFileDesc *fd 938 * Pointer to a PRFileDesc object. 939 * PROffset32, PROffset64 offset 940 * Specifies a value, in bytes, that is used in conjunction 941 * with the 'whence' parameter to set the file pointer. A 942 * negative value causes seeking in the reverse direction. 943 * PRSeekWhence whence 944 * Specifies how to interpret the 'offset' parameter in setting 945 * the file pointer associated with the 'fd' parameter. 946 * Values for the 'whence' parameter are: 947 * PR_SEEK_SET Sets the file pointer to the value of the 948 * 'offset' parameter 949 * PR_SEEK_CUR Sets the file pointer to its current location 950 * plus the value of the offset parameter. 951 * PR_SEEK_END Sets the file pointer to the size of the 952 * file plus the value of the offset parameter. 953 * OUTPUTS: 954 * None. 955 * RETURN: PROffset32, PROffset64 956 * Upon successful completion, the resulting pointer location, 957 * measured in bytes from the beginning of the file, is returned. 958 * If the PR_Seek() function fails, the file offset remains 959 * unchanged, and the returned value is -1. The error code can 960 * then be retrieved via PR_GetError(). 961 ************************************************************************* 962 */ 963 964NSPR_API(PROffset32) PR_Seek(PRFileDesc *fd, PROffset32 offset, PRSeekWhence whence); 965NSPR_API(PROffset64) PR_Seek64(PRFileDesc *fd, PROffset64 offset, PRSeekWhence whence); 966 967/* 968 ************************************************************************ 969 * FUNCTION: PR_Available 970 * DESCRIPTION: 971 * Determine the amount of data in bytes available for reading 972 * in the given file or socket. 973 * INPUTS: 974 * PRFileDesc *fd 975 * Pointer to a PRFileDesc object that refers to a file or 976 * socket. 977 * OUTPUTS: 978 * None 979 * RETURN: PRInt32, PRInt64 980 * Upon successful completion, PR_Available returns the number of 981 * bytes beyond the current read pointer that is available for 982 * reading. Otherwise, it returns a -1 and the reason for the 983 * failure can be retrieved via PR_GetError(). 984 ************************************************************************ 985 */ 986 987NSPR_API(PRInt32) PR_Available(PRFileDesc *fd); 988NSPR_API(PRInt64) PR_Available64(PRFileDesc *fd); 989 990/* 991 ************************************************************************ 992 * FUNCTION: PR_Sync 993 * DESCRIPTION: 994 * Sync any buffered data for a fd to its backing device (disk). 995 * INPUTS: 996 * PRFileDesc *fd 997 * Pointer to a PRFileDesc object that refers to a file or 998 * socket 999 * OUTPUTS: 1000 * None 1001 * RETURN: PRStatus 1002 * PR_SUCCESS is returned if the requested access is permitted. 1003 * Otherwise, PR_FAILURE is returned. 1004 ************************************************************************ 1005 */ 1006 1007NSPR_API(PRStatus) PR_Sync(PRFileDesc *fd); 1008 1009/************************************************************************/ 1010 1011struct PRDirEntry { 1012 const char *name; /* name of entry, relative to directory name */ 1013}; 1014 1015#ifdef MOZ_UNICODE 1016struct PRDirEntryUTF16 { 1017 const PRUnichar *name; /* name of entry in UTF16, relative to 1018 * directory name */ 1019}; 1020#endif /* MOZ_UNICODE */ 1021 1022#if !defined(NO_NSPR_10_SUPPORT) 1023#define PR_DirName(dirEntry) (dirEntry->name) 1024#endif 1025 1026/* 1027 ************************************************************************* 1028 * FUNCTION: PR_OpenDir 1029 * DESCRIPTION: 1030 * Open the directory by the given name 1031 * INPUTS: 1032 * const char *name 1033 * path name of the directory to be opened 1034 * OUTPUTS: 1035 * None 1036 * RETURN: PRDir * 1037 * If the directory is sucessfully opened, a PRDir object is 1038 * dynamically allocated and a pointer to it is returned. 1039 * If the directory cannot be opened, a NULL pointer is returned. 1040 * MEMORY: 1041 * Upon successful completion, the return value points to 1042 * dynamically allocated memory. 1043 ************************************************************************* 1044 */ 1045 1046NSPR_API(PRDir*) PR_OpenDir(const char *name); 1047 1048#ifdef MOZ_UNICODE 1049/* 1050 * EXPERIMENTAL: This function may be removed in a future release. 1051 */ 1052NSPR_API(PRDirUTF16*) PR_OpenDirUTF16(const PRUnichar *name); 1053#endif /* MOZ_UNICODE */ 1054 1055/* 1056 ************************************************************************* 1057 * FUNCTION: PR_ReadDir 1058 * DESCRIPTION: 1059 * INPUTS: 1060 * PRDir *dir 1061 * pointer to a PRDir object that designates an open directory 1062 * PRDirFlags flags 1063 * PR_SKIP_NONE Do not skip any files 1064 * PR_SKIP_DOT Skip the directory entry "." that 1065 * represents the current directory 1066 * PR_SKIP_DOT_DOT Skip the directory entry ".." that 1067 * represents the parent directory. 1068 * PR_SKIP_BOTH Skip both '.' and '..' 1069 * PR_SKIP_HIDDEN Skip hidden files 1070 * OUTPUTS: 1071 * RETURN: PRDirEntry* 1072 * Returns a pointer to the next entry in the directory. Returns 1073 * a NULL pointer upon reaching the end of the directory or when an 1074 * error occurs. The actual reason can be retrieved via PR_GetError(). 1075 ************************************************************************* 1076 */ 1077 1078typedef enum PRDirFlags { 1079 PR_SKIP_NONE = 0x0, 1080 PR_SKIP_DOT = 0x1, 1081 PR_SKIP_DOT_DOT = 0x2, 1082 PR_SKIP_BOTH = 0x3, 1083 PR_SKIP_HIDDEN = 0x4 1084} PRDirFlags; 1085 1086NSPR_API(PRDirEntry*) PR_ReadDir(PRDir *dir, PRDirFlags flags); 1087 1088#ifdef MOZ_UNICODE 1089/* 1090 * EXPERIMENTAL: This function may be removed in a future release. 1091 */ 1092NSPR_API(PRDirEntryUTF16*) PR_ReadDirUTF16(PRDirUTF16 *dir, PRDirFlags flags); 1093#endif /* MOZ_UNICODE */ 1094 1095/* 1096 ************************************************************************* 1097 * FUNCTION: PR_CloseDir 1098 * DESCRIPTION: 1099 * Close the specified directory. 1100 * INPUTS: 1101 * PRDir *dir 1102 * The directory to be closed. 1103 * OUTPUTS: 1104 * None 1105 * RETURN: PRStatus 1106 * If successful, will return a status of PR_SUCCESS. Otherwise 1107 * a value of PR_FAILURE. The reason for the failure may be re- 1108 * trieved using PR_GetError(). 1109 ************************************************************************* 1110 */ 1111 1112NSPR_API(PRStatus) PR_CloseDir(PRDir *dir); 1113 1114#ifdef MOZ_UNICODE 1115/* 1116 * EXPERIMENTAL: This function may be removed in a future release. 1117 */ 1118NSPR_API(PRStatus) PR_CloseDirUTF16(PRDirUTF16 *dir); 1119#endif /* MOZ_UNICODE */ 1120 1121/* 1122 ************************************************************************* 1123 * FUNCTION: PR_MkDir 1124 * DESCRIPTION: 1125 * Create a new directory with the given name and access mode. 1126 * INPUTS: 1127 * const char *name 1128 * The name of the directory to be created. All the path components 1129 * up to but not including the leaf component must already exist. 1130 * PRIntn mode 1131 * See 'mode' definiton in PR_Open(). 1132 * OUTPUTS: 1133 * None 1134 * RETURN: PRStatus 1135 * If successful, will return a status of PR_SUCCESS. Otherwise 1136 * a value of PR_FAILURE. The reason for the failure may be re- 1137 * trieved using PR_GetError(). 1138 ************************************************************************* 1139 */ 1140 1141NSPR_API(PRStatus) PR_MkDir(const char *name, PRIntn mode); 1142 1143/* 1144 ************************************************************************* 1145 * FUNCTION: PR_MakeDir 1146 * DESCRIPTION: 1147 * Create a new directory with the given name and access mode. 1148 * PR_MakeDir has the same prototype as PR_MkDir but implements 1149 * the specified access mode where possible. 1150 ************************************************************************* 1151 */ 1152 1153NSPR_API(PRStatus) PR_MakeDir(const char *name, PRIntn mode); 1154 1155/* 1156 ************************************************************************* 1157 * FUNCTION: PR_RmDir 1158 * DESCRIPTION: 1159 * Remove a directory by the given name. 1160 * INPUTS: 1161 * const char *name 1162 * The name of the directory to be removed. All the path components 1163 * must already exist. Only the leaf component will be removed. 1164 * OUTPUTS: 1165 * None 1166 * RETURN: PRStatus 1167 * If successful, will return a status of PR_SUCCESS. Otherwise 1168 * a value of PR_FAILURE. The reason for the failure may be re- 1169 * trieved using PR_GetError(). 1170 ************************************************************************** 1171 */ 1172 1173NSPR_API(PRStatus) PR_RmDir(const char *name); 1174 1175/* 1176 ************************************************************************* 1177 * FUNCTION: PR_NewUDPSocket 1178 * DESCRIPTION: 1179 * Create a new UDP socket. 1180 * INPUTS: 1181 * None 1182 * OUTPUTS: 1183 * None 1184 * RETURN: PRFileDesc* 1185 * Upon successful completion, PR_NewUDPSocket returns a pointer 1186 * to the PRFileDesc created for the newly opened UDP socket. 1187 * Returns a NULL pointer if the creation of a new UDP socket failed. 1188 * 1189 ************************************************************************** 1190 */ 1191 1192NSPR_API(PRFileDesc*) PR_NewUDPSocket(void); 1193 1194/* 1195 ************************************************************************* 1196 * FUNCTION: PR_NewTCPSocket 1197 * DESCRIPTION: 1198 * Create a new TCP socket. 1199 * INPUTS: 1200 * None 1201 * OUTPUTS: 1202 * None 1203 * RETURN: PRFileDesc* 1204 * Upon successful completion, PR_NewTCPSocket returns a pointer 1205 * to the PRFileDesc created for the newly opened TCP socket. 1206 * Returns a NULL pointer if the creation of a new TCP socket failed. 1207 * 1208 ************************************************************************** 1209 */ 1210 1211NSPR_API(PRFileDesc*) PR_NewTCPSocket(void); 1212 1213/* 1214 ************************************************************************* 1215 * FUNCTION: PR_OpenUDPSocket 1216 * DESCRIPTION: 1217 * Create a new UDP socket of the specified address family. 1218 * INPUTS: 1219 * PRIntn af 1220 * Address family 1221 * OUTPUTS: 1222 * None 1223 * RETURN: PRFileDesc* 1224 * Upon successful completion, PR_OpenUDPSocket returns a pointer 1225 * to the PRFileDesc created for the newly opened UDP socket. 1226 * Returns a NULL pointer if the creation of a new UDP socket failed. 1227 * 1228 ************************************************************************** 1229 */ 1230 1231NSPR_API(PRFileDesc*) PR_OpenUDPSocket(PRIntn af); 1232 1233/* 1234 ************************************************************************* 1235 * FUNCTION: PR_OpenTCPSocket 1236 * DESCRIPTION: 1237 * Create a new TCP socket of the specified address family. 1238 * INPUTS: 1239 * PRIntn af 1240 * Address family 1241 * OUTPUTS: 1242 * None 1243 * RETURN: PRFileDesc* 1244 * Upon successful completion, PR_NewTCPSocket returns a pointer 1245 * to the PRFileDesc created for the newly opened TCP socket. 1246 * Returns a NULL pointer if the creation of a new TCP socket failed. 1247 * 1248 ************************************************************************** 1249 */ 1250 1251NSPR_API(PRFileDesc*) PR_OpenTCPSocket(PRIntn af); 1252 1253/* 1254 ************************************************************************* 1255 * FUNCTION: PR_Connect 1256 * DESCRIPTION: 1257 * Initiate a connection on a socket. 1258 * INPUTS: 1259 * PRFileDesc *fd 1260 * Points to a PRFileDesc object representing a socket 1261 * PRNetAddr *addr 1262 * Specifies the address of the socket in its own communication 1263 * space. 1264 * PRIntervalTime timeout 1265 * Time limit for completion of the connect operation. 1266 * OUTPUTS: 1267 * None 1268 * RETURN: PRStatus 1269 * Upon successful completion of connection initiation, PR_Connect 1270 * returns PR_SUCCESS. Otherwise, it returns PR_FAILURE. Further 1271 * failure information can be obtained by calling PR_GetError(). 1272 ************************************************************************** 1273 */ 1274 1275NSPR_API(PRStatus) PR_Connect( 1276 PRFileDesc *fd, const PRNetAddr *addr, PRIntervalTime timeout); 1277 1278/* 1279 ************************************************************************* 1280 * FUNCTION: PR_ConnectContinue 1281 * DESCRIPTION: 1282 * Continue a nonblocking connect. After a nonblocking connect 1283 * is initiated with PR_Connect() (which fails with 1284 * PR_IN_PROGRESS_ERROR), one should call PR_Poll() on the socket, 1285 * with the in_flags PR_POLL_WRITE | PR_POLL_EXCEPT. When 1286 * PR_Poll() returns, one calls PR_ConnectContinue() on the 1287 * socket to determine whether the nonblocking connect has 1288 * completed or is still in progress. Repeat the PR_Poll(), 1289 * PR_ConnectContinue() sequence until the nonblocking connect 1290 * has completed. 1291 * INPUTS: 1292 * PRFileDesc *fd 1293 * the file descriptor representing a socket 1294 * PRInt16 out_flags 1295 * the out_flags field of the poll descriptor returned by 1296 * PR_Poll() 1297 * RETURN: PRStatus 1298 * If the nonblocking connect has successfully completed, 1299 * PR_ConnectContinue returns PR_SUCCESS. If PR_ConnectContinue() 1300 * returns PR_FAILURE, call PR_GetError(): 1301 * - PR_IN_PROGRESS_ERROR: the nonblocking connect is still in 1302 * progress and has not completed yet. The caller should poll 1303 * on the file descriptor for the in_flags 1304 * PR_POLL_WRITE|PR_POLL_EXCEPT and retry PR_ConnectContinue 1305 * later when PR_Poll() returns. 1306 * - Other errors: the nonblocking connect has failed with this 1307 * error code. 1308 */ 1309 1310NSPR_API(PRStatus) PR_ConnectContinue(PRFileDesc *fd, PRInt16 out_flags); 1311 1312/* 1313 ************************************************************************* 1314 * THIS FUNCTION IS DEPRECATED. USE PR_ConnectContinue INSTEAD. 1315 * 1316 * FUNCTION: PR_GetConnectStatus 1317 * DESCRIPTION: 1318 * Get the completion status of a nonblocking connect. After 1319 * a nonblocking connect is initiated with PR_Connect() (which 1320 * fails with PR_IN_PROGRESS_ERROR), one should call PR_Poll() 1321 * on the socket, with the in_flags PR_POLL_WRITE | PR_POLL_EXCEPT. 1322 * When PR_Poll() returns, one calls PR_GetConnectStatus on the 1323 * PRPollDesc structure to determine whether the nonblocking 1324 * connect has succeeded or failed. 1325 * INPUTS: 1326 * const PRPollDesc *pd 1327 * Pointer to a PRPollDesc whose fd member is the socket, 1328 * and in_flags must contain PR_POLL_WRITE and PR_POLL_EXCEPT. 1329 * PR_Poll() should have been called and set the out_flags. 1330 * RETURN: PRStatus 1331 * If the nonblocking connect has successfully completed, 1332 * PR_GetConnectStatus returns PR_SUCCESS. If PR_GetConnectStatus() 1333 * returns PR_FAILURE, call PR_GetError(): 1334 * - PR_IN_PROGRESS_ERROR: the nonblocking connect is still in 1335 * progress and has not completed yet. 1336 * - Other errors: the nonblocking connect has failed with this 1337 * error code. 1338 */ 1339 1340NSPR_API(PRStatus) PR_GetConnectStatus(const PRPollDesc *pd); 1341 1342/* 1343 ************************************************************************* 1344 * FUNCTION: PR_Accept 1345 * DESCRIPTION: 1346 * Accept a connection on a socket. 1347 * INPUTS: 1348 * PRFileDesc *fd 1349 * Points to a PRFileDesc object representing the rendezvous socket 1350 * on which the caller is willing to accept new connections. 1351 * PRIntervalTime timeout 1352 * Time limit for completion of the accept operation. 1353 * OUTPUTS: 1354 * PRNetAddr *addr 1355 * Returns the address of the connecting entity in its own 1356 * communication space. It may be NULL. 1357 * RETURN: PRFileDesc* 1358 * Upon successful acceptance of a connection, PR_Accept 1359 * returns a valid file descriptor. Otherwise, it returns NULL. 1360 * Further failure information can be obtained by calling PR_GetError(). 1361 ************************************************************************** 1362 */ 1363 1364NSPR_API(PRFileDesc*) PR_Accept( 1365 PRFileDesc *fd, PRNetAddr *addr, PRIntervalTime timeout); 1366 1367/* 1368 ************************************************************************* 1369 * FUNCTION: PR_Bind 1370 * DESCRIPTION: 1371 * Bind an address to a socket. 1372 * INPUTS: 1373 * PRFileDesc *fd 1374 * Points to a PRFileDesc object representing a socket. 1375 * PRNetAddr *addr 1376 * Specifies the address to which the socket will be bound. 1377 * OUTPUTS: 1378 * None 1379 * RETURN: PRStatus 1380 * Upon successful binding of an address to a socket, PR_Bind 1381 * returns PR_SUCCESS. Otherwise, it returns PR_FAILURE. Further 1382 * failure information can be obtained by calling PR_GetError(). 1383 ************************************************************************** 1384 */ 1385 1386NSPR_API(PRStatus) PR_Bind(PRFileDesc *fd, const PRNetAddr *addr); 1387 1388/* 1389 ************************************************************************* 1390 * FUNCTION: PR_Listen 1391 * DESCRIPTION: 1392 * Listen for connections on a socket. 1393 * INPUTS: 1394 * PRFileDesc *fd 1395 * Points to a PRFileDesc object representing a socket that will be 1396 * used to listen for new connections. 1397 * PRIntn backlog 1398 * Specifies the maximum length of the queue of pending connections. 1399 * OUTPUTS: 1400 * None 1401 * RETURN: PRStatus 1402 * Upon successful completion of listen request, PR_Listen 1403 * returns PR_SUCCESS. Otherwise, it returns PR_FAILURE. Further 1404 * failure information can be obtained by calling PR_GetError(). 1405 ************************************************************************** 1406 */ 1407 1408NSPR_API(PRStatus) PR_Listen(PRFileDesc *fd, PRIntn backlog); 1409 1410/* 1411 ************************************************************************* 1412 * FUNCTION: PR_Shutdown 1413 * DESCRIPTION: 1414 * Shut down part of a full-duplex connection on a socket. 1415 * INPUTS: 1416 * PRFileDesc *fd 1417 * Points to a PRFileDesc object representing a connected socket. 1418 * PRIntn how 1419 * Specifies the kind of disallowed operations on the socket. 1420 * PR_SHUTDOWN_RCV - Further receives will be disallowed 1421 * PR_SHUTDOWN_SEND - Further sends will be disallowed 1422 * PR_SHUTDOWN_BOTH - Further sends and receives will be disallowed 1423 * OUTPUTS: 1424 * None 1425 * RETURN: PRStatus 1426 * Upon successful completion of shutdown request, PR_Shutdown 1427 * returns PR_SUCCESS. Otherwise, it returns PR_FAILURE. Further 1428 * failure information can be obtained by calling PR_GetError(). 1429 ************************************************************************** 1430 */ 1431 1432typedef enum PRShutdownHow 1433{ 1434 PR_SHUTDOWN_RCV = 0, /* disallow further receives */ 1435 PR_SHUTDOWN_SEND = 1, /* disallow further sends */ 1436 PR_SHUTDOWN_BOTH = 2 /* disallow further receives and sends */ 1437} PRShutdownHow; 1438 1439NSPR_API(PRStatus) PR_Shutdown(PRFileDesc *fd, PRShutdownHow how); 1440 1441/* 1442 ************************************************************************* 1443 * FUNCTION: PR_Recv 1444 * DESCRIPTION: 1445 * Receive a specified number of bytes from a connected socket. 1446 * The operation will block until some positive number of bytes are 1447 * transferred, a time out has occurred, or there is an error. 1448 * No more than 'amount' bytes will be transferred. 1449 * INPUTS: 1450 * PRFileDesc *fd 1451 * points to a PRFileDesc object representing a socket. 1452 * void *buf 1453 * pointer to a buffer to hold the data received. 1454 * PRInt32 amount 1455 * the size of 'buf' (in bytes) 1456 * PRIntn flags 1457 * must be zero or PR_MSG_PEEK. 1458 * PRIntervalTime timeout 1459 * Time limit for completion of the receive operation. 1460 * OUTPUTS: 1461 * None 1462 * RETURN: PRInt32 1463 * a positive number indicates the number of bytes actually received. 1464 * 0 means the network connection is closed. 1465 * -1 indicates a failure. The reason for the failure is obtained 1466 * by calling PR_GetError(). 1467 ************************************************************************** 1468 */ 1469 1470#define PR_MSG_PEEK 0x2 1471 1472NSPR_API(PRInt32) PR_Recv(PRFileDesc *fd, void *buf, PRInt32 amount, 1473 PRIntn flags, PRIntervalTime timeout); 1474 1475/* 1476 ************************************************************************* 1477 * FUNCTION: PR_Send 1478 * DESCRIPTION: 1479 * Send a specified number of bytes from a connected socket. 1480 * The operation will block until all bytes are 1481 * processed, a time out has occurred, or there is an error. 1482 * INPUTS: 1483 * PRFileDesc *fd 1484 * points to a PRFileDesc object representing a socket. 1485 * void *buf 1486 * pointer to a buffer from where the data is sent. 1487 * PRInt32 amount 1488 * the size of 'buf' (in bytes) 1489 * PRIntn flags 1490 * (OBSOLETE - must always be zero) 1491 * PRIntervalTime timeout 1492 * Time limit for completion of the send operation. 1493 * OUTPUTS: 1494 * None 1495 * RETURN: PRInt32 1496 * A positive number indicates the number of bytes successfully processed. 1497 * This number must always equal 'amount'. A -1 is an indication that the 1498 * operation failed. The reason for the failure is obtained by calling 1499 * PR_GetError(). 1500 ************************************************************************** 1501 */ 1502 1503NSPR_API(PRInt32) PR_Send(PRFileDesc *fd, const void *buf, PRInt32 amount, 1504 PRIntn flags, PRIntervalTime timeout); 1505 1506/* 1507 ************************************************************************* 1508 * FUNCTION: PR_RecvFrom 1509 * DESCRIPTION: 1510 * Receive up to a specified number of bytes from socket which may 1511 * or may not be connected. 1512 * The operation will block until one or more bytes are 1513 * transferred, a time out has occurred, or there is an error. 1514 * No more than 'amount' bytes will be transferred. 1515 * INPUTS: 1516 * PRFileDesc *fd 1517 * points to a PRFileDesc object representing a socket. 1518 * void *buf 1519 * pointer to a buffer to hold the data received. 1520 * PRInt32 amount 1521 * the size of 'buf' (in bytes) 1522 * PRIntn flags 1523 * (OBSOLETE - must always be zero) 1524 * PRNetAddr *addr 1525 * Specifies the address of the sending peer. It may be NULL. 1526 * PRIntervalTime timeout 1527 * Time limit for completion of the receive operation. 1528 * OUTPUTS: 1529 * None 1530 * RETURN: PRInt32 1531 * a positive number indicates the number of bytes actually received. 1532 * 0 means the network connection is closed. 1533 * -1 indicates a failure. The reason for the failure is obtained 1534 * by calling PR_GetError(). 1535 ************************************************************************** 1536 */ 1537 1538NSPR_API(PRInt32) PR_RecvFrom( 1539 PRFileDesc *fd, void *buf, PRInt32 amount, PRIntn flags, 1540 PRNetAddr *addr, PRIntervalTime timeout); 1541 1542/* 1543 ************************************************************************* 1544 * FUNCTION: PR_SendTo 1545 * DESCRIPTION: 1546 * Send a specified number of bytes from an unconnected socket. 1547 * The operation will block until all bytes are 1548 * sent, a time out has occurred, or there is an error. 1549 * INPUTS: 1550 * PRFileDesc *fd 1551 * points to a PRFileDesc object representing an unconnected socket. 1552 * void *buf 1553 * pointer to a buffer from where the data is sent. 1554 * PRInt32 amount 1555 * the size of 'buf' (in bytes) 1556 * PRIntn flags 1557 * (OBSOLETE - must always be zero) 1558 * PRNetAddr *addr 1559 * Specifies the address of the peer. 1560.* PRIntervalTime timeout 1561 * Time limit for completion of the send operation. 1562 * OUTPUTS: 1563 * None 1564 * RETURN: PRInt32 1565 * A positive number indicates the number of bytes successfully sent. 1566 * -1 indicates a failure. The reason for the failure is obtained 1567 * by calling PR_GetError(). 1568 ************************************************************************** 1569 */ 1570 1571NSPR_API(PRInt32) PR_SendTo( 1572 PRFileDesc *fd, const void *buf, PRInt32 amount, PRIntn flags, 1573 const PRNetAddr *addr, PRIntervalTime timeout); 1574 1575/* 1576************************************************************************* 1577** FUNCTION: PR_TransmitFile 1578** DESCRIPTION: 1579** Transmitfile sends a complete file (sourceFile) across a socket 1580** (networkSocket). If headers is non-NULL, the headers will be sent across 1581** the socket prior to sending the file. 1582** 1583** Optionally, the PR_TRANSMITFILE_CLOSE_SOCKET flag may be passed to 1584** transmitfile. This flag specifies that transmitfile should close the 1585** socket after sending the data. 1586** 1587** INPUTS: 1588** PRFileDesc *networkSocket 1589** The socket to send data over 1590** PRFileDesc *sourceFile 1591** The file to send 1592** const void *headers 1593** A pointer to headers to be sent before sending data 1594** PRInt32 hlen 1595** length of header buffers in bytes. 1596** PRTransmitFileFlags flags 1597** If the flags indicate that the connection should be closed, 1598** it will be done immediately after transferring the file, unless 1599** the operation is unsuccessful. 1600.* PRIntervalTime timeout 1601 * Time limit for completion of the transmit operation. 1602** 1603** RETURNS: 1604** Returns the number of bytes written or -1 if the operation failed. 1605** If an error occurs while sending the file, the PR_TRANSMITFILE_CLOSE_ 1606** SOCKET flag is ignored. The reason for the failure is obtained 1607** by calling PR_GetError(). 1608************************************************************************** 1609*/ 1610 1611NSPR_API(PRInt32) PR_TransmitFile( 1612 PRFileDesc *networkSocket, PRFileDesc *sourceFile, 1613 const void *headers, PRInt32 hlen, PRTransmitFileFlags flags, 1614 PRIntervalTime timeout); 1615 1616/* 1617************************************************************************* 1618** FUNCTION: PR_SendFile 1619** DESCRIPTION: 1620** PR_SendFile sends data from a file (sendData->fd) across a socket 1621** (networkSocket). If specified, a header and/or trailer buffer are sent 1622** before and after the file, respectively. The file offset, number of bytes 1623** of file data to send, the header and trailer buffers are specified in the 1624** sendData argument. 1625** 1626** Optionally, if the PR_TRANSMITFILE_CLOSE_SOCKET flag is passed, the 1627** socket is closed after successfully sending the data. 1628** 1629** INPUTS: 1630** PRFileDesc *networkSocket 1631** The socket to send data over 1632** PRSendFileData *sendData 1633** Contains the FD, file offset and length, header and trailer 1634** buffer specifications. 1635** PRTransmitFileFlags flags 1636** If the flags indicate that the connection should be closed, 1637** it will be done immediately after transferring the file, unless 1638** the operation is unsuccessful. 1639.* PRIntervalTime timeout 1640 * Time limit for completion of the send operation. 1641** 1642** RETURNS: 1643** Returns the number of bytes written or -1 if the operation failed. 1644** If an error occurs while sending the file, the PR_TRANSMITFILE_CLOSE_ 1645** SOCKET flag is ignored. The reason for the failure is obtained 1646** by calling PR_GetError(). 1647************************************************************************** 1648*/ 1649 1650struct PRSendFileData { 1651 PRFileDesc *fd; /* file to send */ 1652 PRUint32 file_offset; /* file offset */ 1653 PRSize file_nbytes; /* number of bytes of file data to send */ 1654 /* if 0, send data from file_offset to */ 1655 /* end-of-file. */ 1656 const void *header; /* header buffer */ 1657 PRInt32 hlen; /* header len */ 1658 const void *trailer; /* trailer buffer */ 1659 PRInt32 tlen; /* trailer len */ 1660}; 1661 1662 1663NSPR_API(PRInt32) PR_SendFile( 1664 PRFileDesc *networkSocket, PRSendFileData *sendData, 1665 PRTransmitFileFlags flags, PRIntervalTime timeout); 1666 1667/* 1668************************************************************************* 1669** FUNCTION: PR_AcceptRead 1670** DESCRIPTION: 1671** AcceptRead accepts a new connection, returns the newly created 1672** socket's descriptor and also returns the connecting peer's address. 1673** AcceptRead, as its name suggests, also receives the first block of data 1674** sent by the peer. 1675** 1676** INPUTS: 1677** PRFileDesc *listenSock 1678** A socket descriptor that has been called with the PR_Listen() 1679** function, also known as the rendezvous socket. 1680** void *buf 1681** A pointer to a buffer to receive data sent by the client. This 1682** buffer must be large enough to receive <amount> bytes of data 1683** and two PRNetAddr structures, plus an extra 32 bytes. See: 1684** PR_ACCEPT_READ_BUF_OVERHEAD. 1685** PRInt32 amount 1686** The number of bytes of client data to receive. Does not include 1687** the size of the PRNetAddr structures. If 0, no data will be read 1688** from the client. 1689** PRIntervalTime timeout 1690** The timeout interval only applies to the read portion of the 1691** operation. PR_AcceptRead will block indefinitely until the 1692** connection is accepted; the read will timeout after the timeout 1693** interval elapses. 1694** OUTPUTS: 1695** PRFileDesc **acceptedSock 1696** The file descriptor for the newly connected socket. This parameter 1697** will only be valid if the function return does not indicate failure. 1698** PRNetAddr **peerAddr, 1699** The address of the remote socket. This parameter will only be 1700** valid if the function return does not indicate failure. The 1701** returned address is not guaranteed to be properly aligned. 1702** 1703** RETURNS: 1704** The number of bytes read from the client or -1 on failure. The reason 1705** for the failure is obtained by calling PR_GetError(). 1706************************************************************************** 1707**/ 1708/* define buffer overhead constant. Add this value to the user's 1709** data length when allocating a buffer to accept data. 1710** Example: 1711** #define USER_DATA_SIZE 10 1712** char buf[USER_DATA_SIZE + PR_ACCEPT_READ_BUF_OVERHEAD]; 1713** bytesRead = PR_AcceptRead( s, fd, &a, &p, USER_DATA_SIZE, ...); 1714*/ 1715#define PR_ACCEPT_READ_BUF_OVERHEAD (32+(2*sizeof(PRNetAddr))) 1716 1717NSPR_API(PRInt32) PR_AcceptRead( 1718 PRFileDesc *listenSock, PRFileDesc **acceptedSock, 1719 PRNetAddr **peerAddr, void *buf, PRInt32 amount, PRIntervalTime timeout); 1720 1721/* 1722************************************************************************* 1723** FUNCTION: PR_NewTCPSocketPair 1724** DESCRIPTION: 1725** Create a new TCP socket pair. The returned descriptors can be used 1726** interchangeably; they are interconnected full-duplex descriptors: data 1727** written to one can be read from the other and vice-versa. 1728** 1729** INPUTS: 1730** None 1731** OUTPUTS: 1732** PRFileDesc *fds[2] 1733** The file descriptor pair for the newly created TCP sockets. 1734** RETURN: PRStatus 1735** Upon successful completion of TCP socket pair, PR_NewTCPSocketPair 1736** returns PR_SUCCESS. Otherwise, it returns PR_FAILURE. Further 1737** failure information can be obtained by calling PR_GetError(). 1738** XXX can we implement this on windoze and mac? 1739************************************************************************** 1740**/ 1741NSPR_API(PRStatus) PR_NewTCPSocketPair(PRFileDesc *fds[2]); 1742 1743/* 1744************************************************************************* 1745** FUNCTION: PR_GetSockName 1746** DESCRIPTION: 1747** Get socket name. Return the network address for this socket. 1748** 1749** INPUTS: 1750** PRFileDesc *fd 1751** Points to a PRFileDesc object representing the socket. 1752** OUTPUTS: 1753** PRNetAddr *addr 1754** Returns the address of the socket in its own communication space. 1755** RETURN: PRStatus 1756** Upon successful completion, PR_GetSockName returns PR_SUCCESS. 1757** Otherwise, it returns PR_FAILURE. Further failure information can 1758** be obtained by calling PR_GetError(). 1759************************************************************************** 1760**/ 1761NSPR_API(PRStatus) PR_GetSockName(PRFileDesc *fd, PRNetAddr *addr); 1762 1763/* 1764************************************************************************* 1765** FUNCTION: PR_GetPeerName 1766** DESCRIPTION: 1767** Get name of the connected peer. Return the network address for the 1768** connected peer socket. 1769** 1770** INPUTS: 1771** PRFileDesc *fd 1772** Points to a PRFileDesc object representing the connected peer. 1773** OUTPUTS: 1774** PRNetAddr *addr 1775** Returns the address of the connected peer in its own communication 1776** space. 1777** RETURN: PRStatus 1778** Upon successful completion, PR_GetPeerName returns PR_SUCCESS. 1779** Otherwise, it returns PR_FAILURE. Further failure information can 1780** be obtained by calling PR_GetError(). 1781************************************************************************** 1782**/ 1783NSPR_API(PRStatus) PR_GetPeerName(PRFileDesc *fd, PRNetAddr *addr); 1784 1785NSPR_API(PRStatus) PR_GetSocketOption( 1786 PRFileDesc *fd, PRSocketOptionData *data); 1787 1788NSPR_API(PRStatus) PR_SetSocketOption( 1789 PRFileDesc *fd, const PRSocketOptionData *data); 1790 1791/* 1792 ********************************************************************* 1793 * 1794 * File descriptor inheritance 1795 * 1796 ********************************************************************* 1797 */ 1798 1799/* 1800 ************************************************************************ 1801 * FUNCTION: PR_SetFDInheritable 1802 * DESCRIPTION: 1803 * Set the inheritance attribute of a file descriptor. 1804 * 1805 * INPUTS: 1806 * PRFileDesc *fd 1807 * Points to a PRFileDesc object. 1808 * PRBool inheritable 1809 * If PR_TRUE, the file descriptor fd is set to be inheritable 1810 * by a child process. If PR_FALSE, the file descriptor is set 1811 * to be not inheritable by a child process. 1812 * RETURN: PRStatus 1813 * Upon successful completion, PR_SetFDInheritable returns PR_SUCCESS. 1814 * Otherwise, it returns PR_FAILURE. Further failure information can 1815 * be obtained by calling PR_GetError(). 1816 ************************************************************************* 1817 */ 1818NSPR_API(PRStatus) PR_SetFDInheritable( 1819 PRFileDesc *fd, 1820 PRBool inheritable); 1821 1822/* 1823 ************************************************************************ 1824 * FUNCTION: PR_GetInheritedFD 1825 * DESCRIPTION: 1826 * Get an inherited file descriptor with the specified name. 1827 * 1828 * INPUTS: 1829 * const char *name 1830 * The name of the inherited file descriptor. 1831 * RETURN: PRFileDesc * 1832 * Upon successful completion, PR_GetInheritedFD returns the 1833 * inherited file descriptor with the specified name. Otherwise, 1834 * it returns NULL. Further failure information can be obtained 1835 * by calling PR_GetError(). 1836 ************************************************************************* 1837 */ 1838NSPR_API(PRFileDesc *) PR_GetInheritedFD(const char *name); 1839 1840/* 1841 ********************************************************************* 1842 * 1843 * Memory-mapped files 1844 * 1845 ********************************************************************* 1846 */ 1847 1848typedef struct PRFileMap PRFileMap; 1849 1850/* 1851 * protection options for read and write accesses of a file mapping 1852 */ 1853typedef enum PRFileMapProtect { 1854 PR_PROT_READONLY, /* read only */ 1855 PR_PROT_READWRITE, /* readable, and write is shared */ 1856 PR_PROT_WRITECOPY /* readable, and write is private (copy-on-write) */ 1857} PRFileMapProtect; 1858 1859NSPR_API(PRFileMap *) PR_CreateFileMap( 1860 PRFileDesc *fd, 1861 PRInt64 size, 1862 PRFileMapProtect prot); 1863 1864/* 1865 * return the alignment (in bytes) of the offset argument to PR_MemMap 1866 */ 1867NSPR_API(PRInt32) PR_GetMemMapAlignment(void); 1868 1869NSPR_API(void *) PR_MemMap( 1870 PRFileMap *fmap, 1871 PROffset64 offset, /* must be aligned and sized according to the 1872 * return value of PR_GetMemMapAlignment() */ 1873 PRUint32 len); 1874 1875NSPR_API(PRStatus) PR_MemUnmap(void *addr, PRUint32 len); 1876 1877NSPR_API(PRStatus) PR_CloseFileMap(PRFileMap *fmap); 1878 1879/* 1880 ****************************************************************** 1881 * 1882 * Interprocess communication 1883 * 1884 ****************************************************************** 1885 */ 1886 1887/* 1888 * Creates an anonymous pipe and returns file descriptors for the 1889 * read and write ends of the pipe. 1890 */ 1891 1892NSPR_API(PRStatus) PR_CreatePipe( 1893 PRFileDesc **readPipe, 1894 PRFileDesc **writePipe 1895); 1896 1897/************************************************************************/ 1898/************** The following definitions are for poll ******************/ 1899/************************************************************************/ 1900 1901struct PRPollDesc { 1902 PRFileDesc* fd; 1903 PRInt16 in_flags; 1904 PRInt16 out_flags; 1905}; 1906 1907/* 1908** Bit values for PRPollDesc.in_flags or PRPollDesc.out_flags. Binary-or 1909** these together to produce the desired poll request. 1910*/ 1911 1912#if defined(_PR_POLL_BACKCOMPAT) 1913 1914#include <poll.h> 1915#define PR_POLL_READ POLLIN 1916#define PR_POLL_WRITE POLLOUT 1917#define PR_POLL_EXCEPT POLLPRI 1918#define PR_POLL_ERR POLLERR /* only in out_flags */ 1919#define PR_POLL_NVAL POLLNVAL /* only in out_flags when fd is bad */ 1920#define PR_POLL_HUP POLLHUP /* only in out_flags */ 1921 1922#else /* _PR_POLL_BACKCOMPAT */ 1923 1924#define PR_POLL_READ 0x1 1925#define PR_POLL_WRITE 0x2 1926#define PR_POLL_EXCEPT 0x4 1927#define PR_POLL_ERR 0x8 /* only in out_flags */ 1928#define PR_POLL_NVAL 0x10 /* only in out_flags when fd is bad */ 1929#define PR_POLL_HUP 0x20 /* only in out_flags */ 1930 1931#endif /* _PR_POLL_BACKCOMPAT */ 1932 1933/* 1934************************************************************************* 1935** FUNCTION: PR_Poll 1936** DESCRIPTION: 1937** 1938** The call returns as soon as I/O is ready on one or more of the underlying 1939** socket objects. A count of the number of ready descriptors is 1940** returned unless a timeout occurs in which case zero is returned. 1941** 1942** PRPollDesc.fd should be set to a pointer to a PRFileDesc object 1943** representing a socket. This field can be set to NULL to indicate to 1944** PR_Poll that this PRFileDesc object should be ignored. 1945** PRPollDesc.in_flags should be set to the desired request 1946** (read/write/except or some combination). Upon successful return from 1947** this call PRPollDesc.out_flags will be set to indicate what kind of 1948** i/o can be performed on the respective descriptor. PR_Poll() uses the 1949** out_flags fields as scratch variables during the call. If PR_Poll() 1950** returns 0 or -1, the out_flags fields do not contain meaningful values 1951** and must not be used. 1952** 1953** INPUTS: 1954** PRPollDesc *pds A pointer to an array of PRPollDesc 1955** 1956** PRIntn npds The number of elements in the array 1957** If this argument is zero PR_Poll is 1958** equivalent to a PR_Sleep(timeout). 1959** 1960** PRIntervalTime timeout Amount of time the call will block waiting 1961** for I/O to become ready. If this time expires 1962** w/o any I/O becoming ready, the result will 1963** be zero. 1964** 1965** OUTPUTS: None 1966** RETURN: 1967** PRInt32 Number of PRPollDesc's with events or zero 1968** if the function timed out or -1 on failure. 1969** The reason for the failure is obtained by 1970** calling PR_GetError(). 1971************************************************************************** 1972*/ 1973NSPR_API(PRInt32) PR_Poll( 1974 PRPollDesc *pds, PRIntn npds, PRIntervalTime timeout); 1975 1976/* 1977************************************************************************** 1978** 1979** Pollable events 1980** 1981** A pollable event is a special kind of file descriptor. 1982** The only I/O operation you can perform on a pollable event 1983** is to poll it with the PR_POLL_READ flag. You can't 1984** read from or write to a pollable event. 1985** 1986** The purpose of a pollable event is to combine event waiting 1987** with I/O waiting in a single PR_Poll call. Pollable events 1988** are implemented using a pipe or a pair of TCP sockets 1989** connected via the loopback address, therefore setting and 1990** waiting for pollable events are expensive operating system 1991** calls. Do not use pollable events for general thread 1992** synchronization. Use condition variables instead. 1993** 1994** A pollable event has two states: set and unset. Events 1995** are not queued, so there is no notion of an event count. 1996** A pollable event is either set or unset. 1997** 1998** A new pollable event is created by a PR_NewPollableEvent 1999** call and is initially in the unset state. 2000** 2001** PR_WaitForPollableEvent blocks the calling thread until 2002** the pollable event is set, and then it atomically unsets 2003** the pollable event before it returns. 2004** 2005** To set a pollable event, call PR_SetPollableEvent. 2006** 2007** One can call PR_Poll with the PR_POLL_READ flag on a pollable 2008** event. When the pollable event is set, PR_Poll returns with 2009** the PR_POLL_READ flag set in the out_flags. 2010** 2011** To close a pollable event, call PR_DestroyPollableEvent 2012** (not PR_Close). 2013** 2014************************************************************************** 2015*/ 2016 2017NSPR_API(PRFileDesc *) PR_NewPollableEvent(void); 2018 2019NSPR_API(PRStatus) PR_DestroyPollableEvent(PRFileDesc *event); 2020 2021NSPR_API(PRStatus) PR_SetPollableEvent(PRFileDesc *event); 2022 2023NSPR_API(PRStatus) PR_WaitForPollableEvent(PRFileDesc *event); 2024 2025PR_END_EXTERN_C 2026 2027#endif /* prio_h___ */ 2028