Up

NSFileHandle class reference

Authors

Richard Frith-Macdonald (richard@brainstorm.co.uk)

Version: 1.27

Date: 2003/07/31 23:49:31

Copyright: (C) 1997 Free Software Foundation, Inc.


Contents -

  1. Software documentation for the NSFileHandle class
  2. Software documentation for the NSPipe class
  3. Software documentation for the NSFileHandle(GNUstepExtensions) category
  4. Software documentation for the NSFileHandle(GNUstepOpenSSL) category

Software documentation for the NSFileHandle class

NSFileHandle : NSObject

Declared in:
Foundation/NSFileHandle.h
Standards:

NSFileHandler is a Class that provides a wrapper for accessing system files and other connections. You can open connections to a file using class methods such as +fileHandleForReadingAtPath: .

GNUstep extends the use of this Class to allow you to create network connections (sockets), secure connections and also allows you to use compression with these files and connections (as long as GNUstep Base was compiled with the zlib library).

Method summary

fileHandleForReadingAtPath:

+ (id) fileHandleForReadingAtPath: (NSString*)path;

Returns an NSFileHandle object setup for reading from the file listed at path. If the file does not exist or cannot be opened for some other reason, nil is returned.


fileHandleForUpdatingAtPath:

+ (id) fileHandleForUpdatingAtPath: (NSString*)path;

Returns an NSFileHandle object setup for updating (reading and writing) from the file listed at path. If the file does not exist or cannot be opened for some other reason, nil is returned.


fileHandleForWritingAtPath:

+ (id) fileHandleForWritingAtPath: (NSString*)path;

Returns an NSFileHandle object setup for writing to the file listed at path. If the file does not exist or cannot be opened for some other reason, nil is returned.


fileHandleWithNullDevice

+ (id) fileHandleWithNullDevice;

Returns a file handle object that is connected to the null device (i.e. a device that does nothing.) It is typically used in arrays and other collections of file handle objects as a place holder (null) object, so that all objects can respond to the same messages.


fileHandleWithStandardError

+ (id) fileHandleWithStandardError;

Returns an NSFileHandle object for the standard error descriptor. The returned object is a shared instance as there can only be one standard error per process.


fileHandleWithStandardInput

+ (id) fileHandleWithStandardInput;

Returns an NSFileHandle object for the standard input descriptor. The returned object is a shared instance as there can only be one standard input per process.


fileHandleWithStandardOutput

+ (id) fileHandleWithStandardOutput;

Returns an NSFileHandle object for the standard output descriptor. The returned object is a shared instance as there can only be one standard output per process.


acceptConnectionInBackgroundAndNotify

- (void) acceptConnectionInBackgroundAndNotify;

Description forthcoming.


acceptConnectionInBackgroundAndNotifyForModes:

- (void) acceptConnectionInBackgroundAndNotifyForModes: (NSArray*)modes;

Description forthcoming.


availableData

- (NSData*) availableData;

Description forthcoming.


closeFile

- (void) closeFile;

Description forthcoming.


fileDescriptor

- (int) fileDescriptor;

Description forthcoming.


initWithFileDescriptor:

- (id) initWithFileDescriptor: (int)desc;

Description forthcoming.


initWithFileDescriptor:closeOnDealloc:

- (id) initWithFileDescriptor: (int)desc closeOnDealloc: (BOOL)flag;

Description forthcoming.


initWithNativeHandle:

- (id) initWithNativeHandle: (void*)hdl;

Description forthcoming.


initWithNativeHandle:closeOnDealloc:

- (id) initWithNativeHandle: (void*)hdl closeOnDealloc: (BOOL)flag;

Description forthcoming.


nativeHandle

- (void*) nativeHandle;

Description forthcoming.


offsetInFile

- (unsigned long long) offsetInFile;

Description forthcoming.


readDataOfLength:

- (NSData*) readDataOfLength: (unsigned int)len;

Description forthcoming.


readDataToEndOfFile

- (NSData*) readDataToEndOfFile;

Description forthcoming.


readInBackgroundAndNotify

- (void) readInBackgroundAndNotify;

Call -readInBackgroundAndNotifyForModes: with nil modes.


readInBackgroundAndNotifyForModes:

- (void) readInBackgroundAndNotifyForModes: (NSArray*)modes;

Set up an asynchonous read operation which will cause a notification to be sent when any amount of data (or end of file) is read. Note that the file handle will not continuously send notifications when data is available. If you want to continue to receive notifications, you need to send this message again after receiving a notification.


readToEndOfFileInBackgroundAndNotify

- (void) readToEndOfFileInBackgroundAndNotify;

Call -readToEndOfFileInBackgroundAndNotifyForModes: with nil modes.


readToEndOfFileInBackgroundAndNotifyForModes:

- (void) readToEndOfFileInBackgroundAndNotifyForModes: (NSArray*)modes;

Set up an asynchonous read operation which will cause a notification to be sent when end of file is read.


seekToEndOfFile

- (unsigned long long) seekToEndOfFile;

Description forthcoming.


seekToFileOffset:

- (void) seekToFileOffset: (unsigned long long)pos;

Description forthcoming.


synchronizeFile

- (void) synchronizeFile;

Description forthcoming.


truncateFileAtOffset:

- (void) truncateFileAtOffset: (unsigned long long)pos;

Description forthcoming.


waitForDataInBackgroundAndNotify

- (void) waitForDataInBackgroundAndNotify;

Call -waitForDataInBackgroundAndNotifyForModes: with nil modes.


waitForDataInBackgroundAndNotifyForModes:

- (void) waitForDataInBackgroundAndNotifyForModes: (NSArray*)modes;

Set up to provide a notification when data can be read from the handle.


writeData:

- (void) writeData: (NSData*)item;

Description forthcoming.


Software documentation for the NSPipe class

NSPipe : NSObject

Declared in:
Foundation/NSFileHandle.h
Standards:

The NSPipe provides an encapsulation of the UNIX concept of pipe.
With NSPipe, it is possible to redirect the standard input or standard output.

The file handles created by NSPipe are automatically closed when they are no longer in use (ie when the NSPipe instance is deallocated), so you don't need to close them explicitly.

Method summary

pipe

+ (id) pipe;

Returns a newly allocated and initialized NSPipe object that has been sent an autorelease message.


fileHandleForReading

- (NSFileHandle*) fileHandleForReading;

Returns the file handle for reading from the pipe.


fileHandleForWriting

- (NSFileHandle*) fileHandleForWriting;

Returns the file handle for writing to the pipe.


Software documentation for the NSFileHandle(GNUstepExtensions) category

NSFileHandle(GNUstepExtensions)

Declared in:
Foundation/NSFileHandle.h
Standards:

Description forthcoming.

Method summary

fileHandleAsClientAtAddress:service:protocol:

+ (id) fileHandleAsClientAtAddress: (NSString*)address service: (NSString*)service protocol: (NSString*)protocol;

Opens an outgoing network connection by initiating an asynchronous connection (see +fileHandleAsClientInBackgroundAtAddress:service:protocol:forModes: ) and waiting for it to succeed, fail, or time out.


fileHandleAsClientInBackgroundAtAddress:service:protocol:

+ (id) fileHandleAsClientInBackgroundAtAddress: (NSString*)address service: (NSString*)service protocol: (NSString*)protocol;

Opens an outgoing network connection asynchronously using [+fileHandleAsClientInBackgroundAtAddress:service:protocol:forModes:]


fileHandleAsClientInBackgroundAtAddress:service:protocol:forModes:

+ (id) fileHandleAsClientInBackgroundAtAddress: (NSString*)address service: (NSString*)service protocol: (NSString*)protocol forModes: (NSArray*)modes;

Opens an outgoing network connection asynchronously.

This method supports connection through a firewall via socks5. The socks5 connection may be controlled via the protocol argument, but if no socks infromation is supplied here, the GSSOCKS user default will be used, and failing that, the SOCKS5_SERVER or SOCKS_SERVER environment variables will be used to set the socks server. If none of these mechanisms specify a socks server, the connection will be made directly rather than through socks.


fileHandleAsServerAtAddress:service:protocol:

+ (id) fileHandleAsServerAtAddress: (NSString*)address service: (NSString*)service protocol: (NSString*)protocol;

Opens a network server socket and listens for incoming connections using the specified service and protocol.


readDataInBackgroundAndNotifyLength:

- (void) readDataInBackgroundAndNotifyLength: (unsigned)len;

Call -readDataInBackgroundAndNotifyLength:forModes: with nil modes.


readDataInBackgroundAndNotifyLength:forModes:

- (void) readDataInBackgroundAndNotifyLength: (unsigned)len forModes: (NSArray*)modes;

Set up an asynchonous read operation which will cause a notification to be sent when the specified amount of data (or end of file) is read.


readInProgress

- (BOOL) readInProgress;

Returns a boolean to indicate whether a read operation of any kind is in progress on the handle.


socketAddress

- (NSString*) socketAddress;

Returns the host address of the network connection represented by the file handle. If this handle is an incoming connection which was received by a local server handle, this is the name or address of the client machine.


socketProtocol

- (NSString*) socketProtocol;

Returns the name of the protocol in use for the network connection represented by the file handle.


socketService

- (NSString*) socketService;

Returns the name (or number) of the service (network port) in use for the network connection represented by the file handle.


useCompression

- (BOOL) useCompression;

Return a flag to indicate whether compression has been turned on for the file handle... this is only available on systems where GNUstep was built with 'zlib' support for compressing/decompressing data.

On systems which support it, this method may be called after a file handle has been initialised to turn on compression or decompression of the data being written/read.

Returns YES on success, NO on failure.
Reasons for failure are -


writeInBackgroundAndNotify:

- (void) writeInBackgroundAndNotify: (NSData*)item;

Call -writeInBackgroundAndNotify:forModes: with nil modes.


writeInBackgroundAndNotify:forModes:

- (void) writeInBackgroundAndNotify: (NSData*)item forModes: (NSArray*)modes;

Write the specified data asynchronously, and notify on completion.


writeInProgress

- (BOOL) writeInProgress;

Returns a boolean to indicate whether a write operation of any kind is in progress on the handle. An outgoing network connection attempt (as a client) is considered to be a write operation.


Software documentation for the NSFileHandle(GNUstepOpenSSL) category

NSFileHandle(GNUstepOpenSSL)

Declared in:
Foundation/NSFileHandle.h
Standards:

Description forthcoming.

Method summary

sslClass

+ (Class) sslClass;

returns the concrete class used to implement SSL connections.


sslConnect

- (BOOL) sslConnect;

Establishes an SSL connection to the system that the handle is talking to.


sslDisconnect

- (void) sslDisconnect;

Shuts down the SSL connection to the system that the handle is talking to.


sslSetCertificate:privateKey:PEMpasswd:

- (void) sslSetCertificate: (NSString*)certFile privateKey: (NSString*)privateKey PEMpasswd: (NSString*)PEMpasswd;

Sets the certificate to be used to identify this process to the server at the opposite end of the network connection.



Up