/** Interface for NSFileHandle for GNUStep Copyright (C) 1997 Free Software Foundation, Inc. Written by: Richard Frith-Macdonald Date: 1997 This file is part of the GNUstep Base Library. This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111 USA. AutogsdocSource: NSFileHandle.m AutogsdocSource: NSPipe.m */ #ifndef __NSFileHandle_h_GNUSTEP_BASE_INCLUDE #define __NSFileHandle_h_GNUSTEP_BASE_INCLUDE #import #import #import #if defined(__cplusplus) extern "C" { #endif @class NSData; @class NSString; @interface NSFileHandle : NSObject // Allocating and Initializing a FileHandle Object + (id) fileHandleForReadingAtPath: (NSString*)path; + (id) fileHandleForWritingAtPath: (NSString*)path; + (id) fileHandleForUpdatingAtPath: (NSString*)path; + (id) fileHandleWithStandardError; + (id) fileHandleWithStandardInput; + (id) fileHandleWithStandardOutput; + (id) fileHandleWithNullDevice; - (id) initWithFileDescriptor: (int)desc; - (id) initWithFileDescriptor: (int)desc closeOnDealloc: (BOOL)flag; - (id) initWithNativeHandle: (void*)hdl; - (id) initWithNativeHandle: (void*)hdl closeOnDealloc: (BOOL)flag; // Returning file handles - (int) fileDescriptor; - (void*) nativeHandle; // Synchronous I/O operations - (NSData*) availableData; - (NSData*) readDataToEndOfFile; - (NSData*) readDataOfLength: (unsigned int)len; - (void) writeData: (NSData*)item; // Asynchronous I/O operations - (void) acceptConnectionInBackgroundAndNotify; - (void) acceptConnectionInBackgroundAndNotifyForModes: (NSArray*)modes; - (void) readInBackgroundAndNotify; - (void) readInBackgroundAndNotifyForModes: (NSArray*)modes; - (void) readToEndOfFileInBackgroundAndNotify; - (void) readToEndOfFileInBackgroundAndNotifyForModes: (NSArray*)modes; - (void) waitForDataInBackgroundAndNotify; - (void) waitForDataInBackgroundAndNotifyForModes: (NSArray*)modes; // Seeking within a file - (unsigned long long) offsetInFile; - (unsigned long long) seekToEndOfFile; - (void) seekToFileOffset: (unsigned long long)pos; // Operations on file - (void) closeFile; - (void) synchronizeFile; - (void) truncateFileAtOffset: (unsigned long long)pos; @end // Notification names. /** * Posted when one of the [NSFileHandle] methods * acceptConnectionInBackground... succeeds and has connected to a * stream-type socket in another process. The notification's * userInfo dictionary will contain the [NSFileHandle] for the near * end of the connection (associated to the key * 'NSFileHandleNotificationFileHandleItem'). */ GS_EXPORT NSString * const NSFileHandleConnectionAcceptedNotification; /** * Posted when one of the [NSFileHandle] methods * waitForDataInBackground... has been informed that data is * available. The receiving [NSFileHandle] is passed in the notification. */ GS_EXPORT NSString * const NSFileHandleDataAvailableNotification; /** * Posted when one of the [NSFileHandle] methods readDataInBackground... has * consumed data. The receiving [NSFileHandle] is passed in the * notification's userInfo dictionary associated to the key * 'NSFileHandleNotificationDataItem'. */ GS_EXPORT NSString * const NSFileHandleReadCompletionNotification; /** * Posted when one of the [NSFileHandle] methods * readToEndOfFileInBackground... has finished. The receiving * [NSFileHandle] is passed in the notification's userInfo dictionary * associated to the key 'NSFileHandleNotificationDataItem'. */ GS_EXPORT NSString * const NSFileHandleReadToEndOfFileCompletionNotification; // Keys for accessing userInfo dictionary in notification handlers. /** * Dictionary key for [NSFileHandle] notifications used to access an * [NSData] object containing received data. */ GS_EXPORT NSString * const NSFileHandleNotificationDataItem; /** * Dictionary key for [NSFileHandle] notifications used to mark the * [NSFileHandle] that has established a stream-socket connection. */ GS_EXPORT NSString * const NSFileHandleNotificationFileHandleItem; /** * Dictionary key for [NSFileHandle] notifications postable to certain run * loop modes, associated to an NSArray containing the modes allowed. */ GS_EXPORT NSString * const NSFileHandleNotificationMonitorModes; // Exceptions /** * Exception raised when attempts to read from an [NSFileHandle] channel fail. */ GS_EXPORT NSString * const NSFileHandleOperationException; @interface NSPipe : NSObject { #if GS_EXPOSE(NSPipe) @private NSFileHandle *_readHandle; NSFileHandle *_writeHandle; #endif #if GS_NONFRAGILE #else /* Pointer to private additional data used to avoid breaking ABI * when we don't have the non-fragile ABI available. * Use this mechanism rather than changing the instance variable * layout (see Source/GSInternal.h for details). */ @private id _internal GS_UNUSED_IVAR; #endif } + (id) pipe; - (NSFileHandle*) fileHandleForReading; - (NSFileHandle*) fileHandleForWriting; @end #if OS_API_VERSION(GS_API_NONE, GS_API_NONE) // GNUstep class extensions @interface NSFileHandle (GNUstepExtensions) + (id) fileHandleAsServerAtAddress: (NSString*)address service: (NSString*)service protocol: (NSString*)protocol; + (id) fileHandleAsClientAtAddress: (NSString*)address service: (NSString*)service protocol: (NSString*)protocol; + (id) fileHandleAsClientInBackgroundAtAddress: (NSString*)address service: (NSString*)service protocol: (NSString*)protocol; + (id) fileHandleAsClientInBackgroundAtAddress: (NSString*)address service: (NSString*)service protocol: (NSString*)protocol forModes: (NSArray*)modes; - (void) readDataInBackgroundAndNotifyLength: (unsigned)len; - (void) readDataInBackgroundAndNotifyLength: (unsigned)len forModes: (NSArray*)modes; - (BOOL) readInProgress; - (NSString*) socketAddress; - (NSString*) socketLocalAddress; - (NSString*) socketLocalService; - (NSString*) socketService; - (NSString*) socketProtocol; - (BOOL) useCompression; - (void) writeInBackgroundAndNotify: (NSData*)item forModes: (NSArray*)modes; - (void) writeInBackgroundAndNotify: (NSData*)item; - (BOOL) writeInProgress; @end /** * Where OpenSSL is available, you can use the subclass returned by +sslClass * to handle SSL connections.
* The -sslAccept method is used to do SSL handshake 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 handshake 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.
* NB. Some of these methods may block while performing I/O on the network * connection, (though they should run the current runloop while doing so) * so you should structure your code to handle that. In particular, if you * are writing a server application, you should initiate a background accept * to allow another incoming connection before you perform an * -sslAccept on a connection you have just accepted. */ @interface NSFileHandle (GNUstepTLS) /** Returns the class to handle ssl enabled connections. */ + (Class) sslClass; /** Repeatedly attempt an incoming handshake for up to 30 seconds or until * the handshake completes. */ - (BOOL) sslAccept; /** Repeatedly attempt an outgoing handshake for up to 30 seconds or until * the handshake completes. */ - (BOOL) sslConnect; /** * Shuts down the SSL connection to the system that the handle is talking to. */ - (void) sslDisconnect; /** * Make a non-blocking handshake attempt. Calls to this method should be * repeated until the method returns YES indicating that the handshake * completed. If the method returns YES indicating completion of the * handshake, the result indicates whether the handshake succeeded in * establishing a connection or not.
* The default implementation simply returns YES and sets result to NO.
* This is implemented by an SSL handling subclass to perform real work. */ - (BOOL) sslHandshakeEstablished: (BOOL*)result outgoing: (BOOL)isOutgoing; /** If the session verified a certificate from the remote end, returns the * name of the certificate issuer in the form "C=xxxx,O=yyyy,CN=zzzz" as * described in RFC2253. Otherwise returns nil. */ - (NSString*) sslIssuer; /** If the session verified a certificate from the remote end, returns the * name of the certificate owner in the form "C=xxxx,O=yyyy,CN=zzzz" as * described in RFC2253. Otherwise returns nil. */ - (NSString*) sslOwner; /** Deprecated ... use -sslSetOptions: instead */ - (void) sslSetCertificate: (NSString*)certFile privateKey: (NSString*)privateKey PEMpasswd: (NSString*)PEMpasswd; /** * Sets options to be used to configure this channel before the handshake.
* Returns nil on success, or an error message if some options could not * be set.
* You may use the same options as property settings with the GNUstep * implementation of NSStream.
* Expects key value pairs with the follwing names/meanings: * * GSTLSCAFile * A string identifying the full path to the file containing any * trusted certificate authorities to be used when verifying a certificate * presented by the remote end of a connection. * * GSTLSCertificateFile * The path to a PEM encoded certificate used to identify this end * of the connection. This option must be set for handing an * incoming connection, but is optional for outgoing connections.
* This must be used in conjunction with GSTLSCertificateKeyFile. * * GSTLSCertificateKeyFile * The path to a PEM encoded key used to unlock the certificate * file for the connection. The key in the file may or may not be * encrypted, but if it is encrypted you must specify * GSTLSCertificateKeyPassword. * * GSTLSCertificateKeyPassword * A string to be used as the password to decrypt a key which was * specified using GSTLSKeyPassword. * * GSTLSDebug * A boolean specifying whether diagnostic debug is to be enabled * to log information about a connection where the handshake fails.
* * GSTLSPriority * A GNUTLS priority string describing the ciphers etc which may be * used for the connection. In addition the string may be one of * SSLv3, or TLSv1 to use the appropriate general settings * for negotiating a connection of the specified type. * * GSTLSRemoteHosts * A comma delimited list of host names to be allowed when verifying * the certificate of the host we are connecting to.
* If this is not specified, all the names provided by NSHost are used. * * GSTLSRevokeFile * The full path of a file containing certificate revocation * information for certificates issued by our trusted authorites but * no longer valid. * * GSTLSVerify * A boolean specifying whether we should require the remote end to * supply a valid certificate in order to establish an encrypted connection. * * */ - (NSString*) sslSetOptions: (NSDictionary*)options; /** Sets the known (cached) data content for the specified file name.
* Calling this with a nil data object will remove any existing value * from the cache.
* You may use this method to control what data is used for specified * file names when those file names are used as a result of SSL/TLS * options being set for a file handle or stream. */ + (void) setData: (NSData*)data forTLSFile: (NSString*)fileName; @end /** Dictionary key for the path to a PEM encoded certificate authority * file. */ GS_EXPORT NSString * const GSTLSCAFile; /** Dictionary key for the path to a PEM encoded certificate used * to identify this end of a connection. */ GS_EXPORT NSString * const GSTLSCertificateFile; /** Dictionary key for the path to a PEM encoded private key used * to unlock the certificate used by this end of a connection. */ GS_EXPORT NSString * const GSTLSCertificateKeyFile; /** Dictionary key for the password used to decrypt the key file used * to unlock the certificate used by this end of a connection. */ GS_EXPORT NSString * const GSTLSCertificateKeyPassword; /** Dictionary key for a boolean to enable TLS debug for a session. */ GS_EXPORT NSString * const GSTLSDebug; /** Dictionary key for a GNUTLS priority setting for a session. */ GS_EXPORT NSString * const GSTLSPriority; /** Dictionary key for a list of hosts to use in certificate verification. */ GS_EXPORT NSString * const GSTLSRemoteHosts; /** Dictionary key for the path to a PEM encoded certificate revocation * file. */ GS_EXPORT NSString * const GSTLSRevokeFile; /** Dictionary key for a boolean to enable certificate verification. */ GS_EXPORT NSString * const GSTLSVerify; // GNUstep Notification names. /** * Notification posted when an asynchronous [NSFileHandle] connection * attempt (to an FTP, HTTP, or other internet server) has succeeded. */ GS_EXPORT NSString * const GSFileHandleConnectCompletionNotification; /** * Notification posted when an asynchronous [NSFileHandle] write * operation (to an FTP, HTTP, or other internet server) has succeeded. */ GS_EXPORT NSString * const GSFileHandleWriteCompletionNotification; /** * Message describing error in asynchronous [NSFileHandle] accept,read,write * operation. */ GS_EXPORT NSString * const GSFileHandleNotificationError; #endif #if defined(__cplusplus) } #endif #if !NO_GNUSTEP && !defined(GNUSTEP_BASE_INTERNAL) #import #endif #endif /* __NSFileHandle_h_GNUSTEP_BASE_INCLUDE */