richard@brainstorm.co.uk
)Version: 1.31
Date: 2004/08/18 10:12:13
Copyright: (C) 1997 Free Software Foundation, Inc.
- Declared in:
- Foundation/NSFileHandle.h
Standards:
- MacOS-X
- OpenStep
- GNUstep
NSFileHandle
is a class that provides a
wrapper for accessing system files and socket
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
Returns an NSFileHandle
object set up
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.
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.
Returns an NSFileHandle
object set up
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.
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.
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.
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.
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.
Asynchronously accept a stream-type socket
connection and act as the (server) end of the
communications channel. This instance should
have been created by
-initWithFileDescriptor:
with a stream-type socket created by the appropriate
system routine. Posts a
NSFileHandleConnectionAcceptedNotification
when connection initiated, returning an
NSFileHandle
for the client side with
that notification.
Asynchronously accept a stream-type socket
connection and act as the (server) end of the
communications channel. This instance
should have been created by
-initWithFileDescriptor:
with a stream-type socket created by the appropriate
system routine. Posts a
NSFileHandleConnectionAcceptedNotification
when connection initiated, returning an
NSFileHandle
for the client side with
that notification.
The modes array specifies NSRunLoop modes that the notification can be posted in.
Synchronously returns data available through
this file or connection. If the handle represents a
file, the entire contents from current file pointer
to end are returned. If this is a network connection,
reads what is available, blocking if nothing is
available. Raises
NSFileHandleOperationException
if
problem encountered.
Disallows further reading from read-access files or connections, and sends EOF on write-access files or connections. Descriptor is only deleted when this instance is deallocated.
Return the underlying file descriptor for this instance.
Initialize with desc, which can point to either a regular file or socket connection.
Initialize with desc, which can point
to either a regular file or socket connection. Close
desc when this instance is deallocated if
flag is YES
.
Windows-Unix compatibility support.
Windows-Unix compatibility support.
Windows-Unix compatibility support.
Return current position in file, or raises exception if instance does not represent a regular file.
Reads up to len bytes from file or communications channel into return data.
Reads up to maximum unsigned int bytes from file or communications channel into return data.
Call
-readInBackgroundAndNotifyForModes:
with nil
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.
Call
-readToEndOfFileInBackgroundAndNotifyForModes:
with nil
modes.
Set up an asynchonous read operation which will cause a notification to be sent when end of file is read.
Position file pointer at end of file, raising exception if instance does not represent a regular file.
Position file pointer at pos, raising exception if instance does not represent a regular file.
Flush in-memory buffer to file or connection, then return.
Chops file beyond pos then sets file pointer to that point.
Call
-waitForDataInBackgroundAndNotifyForModes:
with nil
modes.
Set up to provide a notification when data can be read from the handle.
Synchronously writes given data item to file or connection.
- Declared in:
- Foundation/NSFileHandle.h
Standards:
- MacOS-X
- OpenStep
- GNUstep
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.
Returns a newly allocated and initialized NSPipe object that has been sent an autorelease message.
Returns the file handle for reading from the pipe.
Returns the file handle for writing to the pipe.
Description forthcoming.
Description forthcoming.
- Declared in:
- Foundation/NSFileHandle.h
Standards:
- NotOpenStep
- NotMacOS-X
- GNUstep
A set of convenience methods for utilizing the socket communications capabilities of the NSFileHandle class.
Method summaryOpens an outgoing network connection by initiating an asynchronous connection (see +fileHandleAsClientInBackgroundAtAddress:service:protocol:forModes: ) and waiting for it to succeed, fail, or time out.
Opens an outgoing network connection asynchronously using [+fileHandleAsClientInBackgroundAtAddress:service:protocol:forModes:]
Opens an outgoing network connection asynchronously.
nil
or empty,
uses NSDefaultRunLoopMode.
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.
Opens a network server socket and listens for incoming connections using the specified service and protocol.
Call
-readDataInBackgroundAndNotifyLength:forModes:
with nil
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.
Returns a boolean to indicate whether a read operation of any kind is in progress on the handle.
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.
Returns the local address of the network connection
or nil
.
Returns the local service/port of the network
connection or nil
.
Returns the name of the protocol in use for the network connection represented by the file handle.
Returns the name (or number) of the service (network port) in use for the network connection represented by the file handle.
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 -
Call
-writeInBackgroundAndNotify:forModes:
with nil
modes.
Write the specified data asynchronously, and notify on completion.
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.
- Declared in:
- Foundation/NSFileHandle.h
Standards:
- NotOpenStep
- NotMacOS-X
- GNUstep
Where OpenSSL is available, you can use the subclass returned by +sslClass to handle SSL connections. The -sslAccept method is used to do SSL handlshake and start an encrypted session on a channel where the connection was initiated from the far end. The -sslConnect method is used to do SSL handlshake and start an encrypted session on a channel where the connection was initiated from the near end.. The -sslDisconnect method is used to end the encrypted session. The -sslSetCertificate:privateKey:PEMpasswd: method is used to establish a client certificate before starting an encrypted session.
Method summaryreturns the concrete class used to implement SSL connections.
Establishes an SSL connection from the system that the handle is talking to.
Establishes an SSL connection to the system that the handle is talking to.
Shuts down the SSL connection to the system that the handle is talking to.
Sets the certificate to be used to identify this process to the server at the opposite end of the network connection.