|
[Contents] [Previous] [Next] [Last]
This chapter describes the most common NSPR types, enumerations, and structures used with the functions described in Chapter 10, "I/O Functions" and Chapter 11, "Network Addresses." These include the types used for system access, normal file I/O, and socket (network) I/O.
Types unique to a particular function are described with the function itself.
For sample code that illustrates basic I/O operations, see Introduction to NSPR.
Directory Type
File Descriptor Types
File Info Types
Network Address Types
Types Used with Socket Options Functions
Type Used with Memory-Mapped I/O
Offset Interpretation for Seek Functions
Directory Type
PRDir
Directory structure used with Directory I/O Functions.
Syntax
#include <prio.h>
typedef struct PRDir PRDir;
Description
The opaque structure PRDir represents an open directory in the file system. The function PR_OpenDir opens a specified directory and returns a pointer to a PRDir structure, which can be passed to PR_ReadDir repeatedly to obtain successive entries (files or subdirectories in the open directory). To close the directory, pass the PRDir pointer to PR_CloseDir.
File Descriptor Types
NSPR represents I/O objects, such as open files and sockets, by file descriptors of type PRFileDesc. This section introduces PRFileDesc and related types.
PRFileDesc
PRIOMethods
PRFilePrivate
PRDescIdentity
Note that the NSPR documentation follows the Unix convention of using the term files to refer to many kinds of I/O objects. To refer specifically to the files in a file system (that is, disk files), this documentation uses the term normal files.
PRFileDesc has an object-oriented flavor. An I/O function on a PRFileDesc structure is carried out by invoking the corresponding "method" in the I/O methods table (a structure of type PRIOMethods) of the PRFileDesc structure (the "object"). Different kinds of I/O objects (such as files and sockets) have different I/O methods tables, thus implementing different behavior in response to the same I/O function call.
NSPR supports the implementation of layered I/O. Each layer is represented by a PRFileDesc structure, and the PRFileDesc structures for the layers are chained together. Each PRFileDesc structure has a field (of type PRDescIdentity) to identify itself in the layers. For example, the Netscape implementation of the Secure Sockets Layer (SSL) protocol is implemented as an I/O layer on top of NSPR's socket layer.
PRFileDesc
A file descriptor used to represent any open file, such as a normal file, an end point of a pipe, or a socket (end point of network communication).
Syntax
#include <prio.h>
struct PRFileDesc {
PRIOMethods *methods;
PRFilePrivate *secret;
PRFileDesc *lower, *higher;
void (*dtor)(PRFileDesc *fd);
PRDescIdentity identity;
};
typedef struct PRFileDesc PRFileDesc;
Fields
The structure has the following fields:
Description
The fields of this structure are significant only if you are implementing a layer on top of NSPR, such as SSL. Otherwise, you use functions such as PR_Open and PR_NewTCPSocket to obtain a file descriptor, which you should treat as an opaque structure.
For more details about the use of PRFileDesc and related structures, see File Descriptor Types.
PRIOMethods
The table of I/O methods used in a file descriptor.
Syntax
#include <prio.h>
struct PRIOMethods {
PRDescType file_type;
PRCloseFN close;
PRReadFN read;
PRWriteFN write;
PRAvailableFN available;
PRAvailable64FN available64;
PRFsyncFN fsync;
PRSeekFN seek;
PRSeek64FN seek64;
PRFileInfoFN fileInfo;
PRFileInfo64FN fileInfo64;
PRWritevFN writev;
PRConnectFN connect;
PRAcceptFN accept;
PRBindFN bind;
PRListenFN listen;
PRShutdownFN shutdown;
PRRecvFN recv;
PRSendFN send;
PRRecvfromFN recvfrom;
PRSendtoFN sendto;
PRPollFN poll;
PRAcceptreadFN acceptread;
PRTransmitfileFN transmitfile;
PRGetsocknameFN getsockname;
PRGetpeernameFN getpeername;
PRGetsockoptFN getsockopt;
PRSetsockoptFN setsockopt;
};
typedef struct PRIOMethods PRIOMethods;
Fields
The structure has the following fields:
Description
You don't need to know the type declaration for each function listed in the method table unless you are implementing a layer. For information about each function, see the corresponding function description in this document. For example, the write method in PRIOMethods implements the PR_Write function. For type definition details, see prio.h.
The I/O methods table provides procedural access to the functions of the file descriptor. It is the responsibility of a layer implementor to provide suitable functions at every entry point (that is, for every function in the I/O methods table). If a layer provides no functionality, it should call the next lower (higher) function of the same name (for example, the "close" method would return fd->lower->method->close(fd->lower)).
Not all functions in the methods table are implemented for all types of files. For example, the seek method is implemented for normal files but not for sockets. In cases where this partial implementation occurs, the function returns an error indication with an error code of PR_INVALID_METHOD_ERROR.
PRFilePrivate
Layer-dependent implementation data.
Syntax
#include <prio.h>
typedef struct PRFilePrivate PRFilePrivate;
Description
A layer implementor should collect all the private data of the layer in the PRFilePrivate structure. Each layer has its own definition of PRFilePrivate, which is hidden from other layers as well as from the users of the layer.
PRDescIdentity
The identity of a file descriptor's layer.
Syntax
#include <prio.h>
typedef PRUintn PRDescIdentity;
Description
File descriptors may be layered. Each layer has it own identity. Identities are allocated by the runtime and are to be associated (by the layer implementor) with all file descriptors of that layer. It is then possible to scan the chain of layers and find a layer that one recognizes, then predict that it will implement a desired protocol.
A string may be associated with a layer when the layer is created. The string is copied by the runtime, and PR_GetNameForIdentity returns a reference to that copy. There is no way to delete a layer's identity after the layer is created.
File Info Types
PRFileInfo
PRFileInfo64
PRFileType
PRFileInfo
File information structure used with PR_GetFileInfo and PR_GetOpenFileInfo.
Syntax
#include <prio.h>
struct PRFileInfo {
PRFileType type;
PRUint32 size;
PRTime creationTime;
PRTime modifyTime;
};
typedef struct PRFileInfo PRFileInfo;
Fields
The structure has the following fields:
Description
The PRFileInfo structure provides information about a file, a directory, or some other kind of file system object, as specified by the type field.
PRFileInfo64
File information structure used with PR_GetFileInfo64 and PR_GetOpenFileInfo64.
Syntax
#include <prio.h>
struct PRFileInfo64 {
PRFileType type;
PRUint64 size;
PRTime creationTime;
PRTime modifyTime;
};
typedef struct PRFileInfo64 PRFileInfo64;
Fields
The structure has the following fields:
Description
The PRFileInfo64 structure provides information about a file, a directory, or some other kind of file system object, as specified by the type field.
PRFileType
Type for enumerators used in the type field of the PRFileInfo and PRFileInfo64 structures.
Syntax
#include <prio.h>
typedef enum PRFileType{
PR_FILE_FILE = 1,
PR_FILE_DIRECTORY = 2,
PR_FILE_OTHER = 3
} PRFileType;
Enumerators
The enumeration has the following enumerators:
Network Address Types
PRNetAddr
PRIPv6Addr
PRNetAddr
Type used with Socket Manipulation Functions to specify a network address.
Syntax
#include <prio.h>
union PRNetAddr {
struct {
PRUint16 family;
char data[14];
} raw;
struct {
PRUint16 family;
PRUint16 port;
PRUint32 ip;
char pad[8];
} inet;
#if defined(_PR_INET6)
struct {
PRUint16 family;
PRUint16 port;
PRUint32 flowinfo;
PRIPv6Addr ip;
} ipv6;
#endif /* defined(_PR_INET6) */
#if defined(XP_UNIX)
struct {
PRUint16 family;
char path[104];
} local;
};
typedef union PRNetAddr PRNetAddr;
Fields
The structure has the following fields:
Description
The union PRNetAddr represents a network address. NSPR supports only the Internet address family. By default, NSPR is built to support only IPv4, but it's possible to build the NSPR library to support both IPv4 and IPv6. Therefore, the family field can be AF_INET only for default NSPR, and can also be AF_INET6 if the binary supports IPv6.
PRNetAddr is binary-compatible with the socket address structures in the familiar Berkeley socket interface, although this fact should not be relied upon. The raw member of the union is equivalent to struct sockaddr, the inet member is equivalent to struct sockaddr_in, and if the binary is built with IPv6 support, the ipv6 member is equivalent to struct sockaddr_in6. (Note that PRNetAddr does not have the length field that is present in struct sockaddr_in on some Unix platforms.)
The macros AF_INET, AF_INET6, INADDR_ANY, INADDR_LOOPBACK are defined if prio.h is included. INADDR_ANY and INADDR_LOOPBACK are special IPv4 addresses in host byte order, so they must be converted to network byte order before being assigned to the inet.ip field.
PRIPv6Addr
Type used in the ipv6.ip field of the PRNetAddr structure.
Syntax
#include <prio.h>
#if defined(_PR_INET6)
typedef struct in6_addr PRIPv6Addr;
#endif /* defined(_PR_INET6) */
Description
PRIPv6Addr represents a 128-bit IPv6 address. It is equivalent to struct in6_addr in the Berkeley socket interface. PRIPv6Addr is always manipulated as a byte array. Unlike the IPv4 address (a 4-byte unsigned integer) or the port number (a 2-byte unsigned integer), it has no network or host byte order.
Types Used with Socket Options Functions
PRSocketOptionData
PRSockOption
PRLinger
PRMcastRequest
PRSocketOptionData
Type for structure used with PR_GetSocketOption and PR_SetSocketOption to specify options for file descriptors that represent sockets.
Syntax
#include <prio.h>
typedef struct PRSocketOptionData
{
PRSockOption option;
union
{
PRUintn ip_ttl;
PRUintn mcast_ttl;
PRUintn tos;
PRBool non_blocking;
PRBool reuse_addr;
PRBool keep_alive;
PRBool mcast_loopback;
PRBool no_delay;
PRSize max_segment;
PRSize recv_buffer_size;
PRSize send_buffer_size;
PRLinger linger;
PRMcastRequest add_member;
PRMcastRequest drop_member;
PRNetAddr mcast_if;
} value;
} PRSocketOptionData;
Fields
The structure has the following fields:
Description
PRSocketOptionData is a name-value pair for a socket option. The option field (of enumeration type PRSockOption) specifies the name of the socket option, and the value field (a union of all possible values) specifies the value of the option.
PRSockOption
Enumeration type used in the option field of PRSocketOptionData to form the name portion of a name-value pair.
Syntax
#include <prio.h>
typedef enum PRSockOption {
PR_SockOpt_Nonblocking,
PR_SockOpt_Linger,
PR_SockOpt_Reuseaddr,
PR_SockOpt_Keepalive,
PR_SockOpt_RecvBufferSize,
PR_SockOpt_SendBufferSize,
PR_SockOpt_IpTimeToLive,
PR_SockOpt_IpTypeOfService,
PR_SockOpt_AddMember,
PR_SockOpt_DropMember,
PR_SockOpt_McastInterface,
PR_SockOpt_McastTimeToLive,
PR_SockOpt_McastLoopback,
PR_SockOpt_NoDelay,
PR_SockOpt_MaxSegment,
PR_SockOpt_Last
} PRSockOption;
Enumerators
The enumeration has the following enumerators:
Description
The PRSockOption enumeration consists of all the socket options supported by NSPR. The option field of PRSocketOptionData should be set to an enumerator of type PRSockOption.
PRLinger
Structure used with the PR_SockOpt_Linger socket option to specify the time interval (in PRIntervalTime units) to linger on closing a socket if any data remain in the socket send buffer.
Syntax
#include <prio.h>
typedef struct PRLinger {
PRBool polarity;
PRIntervalTime linger;
} PRLinger;
Fields
The structure has the following fields:
Description
By default, PR_Close returns immediately, but if there are any data remaining in the socket send buffer, the system attempts to deliver the data to the peer. The PR_SockOpt_Linger socket option, with a value represented by a structure of type PRLinger, makes it possible to change this default as follows:
PRMcastRequest
Structure used to specify values for the PR_SockOpt_AddMember and PR_SockOpt_DropMember socket options that define a request to join or leave a multicast group.
Syntax
#include <prio.h>
struct PRMcastRequest {
PRNetAddr mcaddr;
PRNetAddr ifaddr;
};
typedef struct PRMcastRequest PRMcastRequest;
Fields
The structure has the following fields:
Description
The mcaddr and ifaddr fields are of the type PRNetAddr, but their port fields are ignored. Only the IP address (inet.ip) fields are used.
Type Used with Memory-Mapped I/O
PRFileMap
Type returned by PR_CreateFileMap and passed to PR_MemMap and PR_CloseFileMap.
Syntax
#include <prio.h>
typedef struct PRFileMap PRFileMap;
Description
The opaque structure PRFileMap represents a memory-mapped file object. Before actually mapping a file to memory, you must create a memory-mapped file object by calling PR_CreateFileMap, which returns a pointer to PRFileMap. Then sections of the file can be mapped into memory by passing the PRFileMap pointer to PR_MemMap. The memory-mapped file object is closed by passing the PRFileMap pointer to PR_CloseFileMap.
Offset Interpretation for Seek Functions
PRSeekWhence
Specifies how to interpret the offset parameter in setting the file pointer associated with the fd parameter for the PR_Seek and PR_Seek64 functions.
Syntax
#include <prio.h>
typedef PRSeekWhence {
PR_SEEK_SET = 0,
PR_SEEK_CUR = 1,
PR_SEEK_END = 2
} PRSeekWhence;
Enumerators
The enumeration has the following enumerators:
[Contents] [Previous] [Next] [Last]
Last Updated: Mon Jul 13 17:41:32 PDT 1998
Copyright © 1998
Netscape Communications Corporation
|
