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