PATH  Documentation > Mac OS X > Foundation Reference: Objective-C



Table of Contents

NSPort


Inherits from:
NSObject
Conforms to:
NSCoding
NSCopying
NSObject (NSObject)
Declared in:
Foundation/NSPort.h




Class Description


An NSPort represents a communication channel to or from another NSPort, which typically resides in a different thread or task. The distributed objects system uses NSPort objects to send NSPortMessages back and forth. You should implement interapplication communication using distributed objects whenever possible, and use NSPorts only when necessary.


Note: An NSPort is essentially the object form of a Mach port. To use NSPorts effectively you should be familiar with Mach ports, port access rights, and Mach messages. See the Mach OS documentation for more information.When an NSPort receives an NSPortMessage, it forwards the message to its delegate in a handleMachMessage: or handlePortMessage: message. The delegate should implement only one of these methods to process the incoming message in whatever form desired. handleMachMessage: provides a message as a raw Mach message beginning with a msg_header_t structure. handlePortMessage: provides a message as an NSPortMessage object, which is an object-oriented wrapper for a Mach message.NSPort is intended to receive incoming messages that need to be added to an NSRunLoop. See the NSRunLoop class specification for more information.




Adopted Protocols


NSCoding
- encodeWithCoder:
- initWithCoder:
NSCopying
- copyWithZone:


Method Types


Creating instances
+ allocWithZone:
+ port
Validation
- invalidate
- isValid
Setting the delegate
- setDelegate:
- delegate
Creating connections
- addConnection:toRunLoop:forMode:
- removeConnection:fromRunLoop:forMode:
Setting information
- sendBeforeDate:components:from:reserved:
- sendBeforeDate:msgid:components:from:reserved:
- reservedSpaceLength
Port monitoring
- removeFromRunLoop:forMode:
- scheduleInRunLoop:forMode:


Class Methods



allocWithZone:

+ (id)allocWithZone:(NSZone *)zone

For backwards compatibility on Mach, allocWithZone: returns an instance of the NSMachPort class when sent to the NSPort class.

Otherwise, it returns an instance of a concrete subclass which can be used for messaging between threads or processes on the local machine.



port

+ (NSPort *)port

Creates and returns a new NSPort object capable of both sending and receiving messages.


Instance Methods



addConnection:toRunLoop:forMode:

- (void)addConnection:(NSConnection *)connection toRunLoop:(NSRunLoop *)runLoop forMode:(NSString *)mode

Adds the receiver to the list of ports monitored by runLoop for the given input mode. You should not call this method directly. The method is provided for subclassers who wish to provide their own custom types of NSPort. NSConnection calls this method at the appropriate times. See the TCP Transport example in /System/Developer/Examples/Foundation for an example implementation.

See Also: addPort:forMode: (NSRunLoop)



delegate

- (id)delegate

Returns the NSPort's delegate.

See Also: - setDelegate:



invalidate

- (void)invalidate

Marks the NSPort as invalid and posts an NSPortDidBecomeInvalidNotification to the default notification center.

See Also: - isValid



isValid

- (BOOL)isValid

Returns NO if the NSPort is known to be invalid, YES otherwise (an NSPort only notes that it has become invalid when it tries to send or receive a message). An NSPort becomes invalid when its underlying communication resource, which is operating-system dependent, is closed or damaged.

See Also: - invalidate



removeConnection:fromRunLoop:forMode:

- (void)removeConnection:(NSConnection *)connection fromRunLoop:(NSRunLoop *)runLoop forMode:(NSString *)mode

Removes the receiver from the list of ports monitored by runLoop in the given input mode. You should not call this method directly. The method is provided for subclassers who wish to provide their own custom types of NSPort. NSConnection calls this method at the appropriate times. See the TCP Transport example in /System/Developer/Examples/Foundation for an example implementation.

removeFromRunLoop:forMode:

- (void)removeFromRunLoop:(NSRunLoop *)runLoop forMode:(NSString *)mode

This method should be implemented by a subclass to stop monitoring of a port when removed from a run loop. This method should not be called directly.

See Also: - scheduleInRunLoop:forMode:



reservedSpaceLength

- (unsigned)reservedSpaceLength

Returns the amount of space reserved by the port for sending data.The default length is zero.

scheduleInRunLoop:forMode:

- (void)scheduleInRunLoop:(NSRunLoop *)runLoop forMode:(NSString *)mode

This method should be implemented by a subclass to setup monitoring of a port when added to a run loop. This method should not be called directly.

See Also: - removeFromRunLoop:forMode:



sendBeforeDate:components:from:reserved:

- (BOOL)sendBeforeDate:(NSDate *)limitDate components:(NSMutableArray *)components from:(NSPort *)receivePort reserved:(unsigned)headerSpaceReserved

You should not call this method directly. The method is provided for subclassers who wish to provide their own custom types of NSPort. NSConnection calls this method at the appropriate times. See the TCP Transport example in /System/Developer/Examples/Foundation for an example implementation.

sendBeforeDate:msgid:components:from:reserved:

- (BOOL)sendBeforeDate:(NSDate *)limitDate msgid:(unsigned)msgID components:(NSMutableArray *)components from:(NSPort *)receivePort reserved:(unsigned)headerSpaceReserved

You should not call this method directly. The method is provided for subclassers who wish to provide their own custom types of NSPort. NSConnection calls this method at the appropriate times. See the TCP Transport example in /System/Developer/Examples/Foundation for an example implementation.

setDelegate:

- (void)setDelegate:(id)anObject

Sets the NSPort's delegate to anObject. Doesn't retain anObject.

See Also: - delegate




Methods Implemented By the Delegate


handleMachMessage:

- (void)handleMachMessage:(void *)machMessage

Processes machMessage, an incoming Mach message cast as a pointer to void. The delegate should interpret this data as a pointer to a Mach message beginning with a msg_header_t structure and should handle the message appropriately.

The delegate should implement only one of handleMachMessage: and handlePortMessage:.



handlePortMessage:

- (void)handlePortMessage:(NSPortMessage *)portMessage

Processes portMessage, an incoming message on the NSPort. See the NSPortMessage class specification for more information.

The delegate should implement only one of handleMachMessage: and handlePortMessage:.




Notifications


NSPortDidBecomeInvalidNotification

Posted from the invalidate method, which is invoked when the NSPort is deallocated or when it notices that its communication channel has been damaged. This notification contains a notification object but no userInfo dictionary. The notification object is the NSPort object that has become invalid.

The NSPort object posting this notification is no longer useful, so all receivers should unregister themselves for any notifications involving the NSPort. A method receiving this notification should check to see which port became invalid before attempting to do anything. In particular, observers that receive all NSPortDidBecomeInvalidNotification's should be aware that communication with the window server is handled through an NSPort. If this port becomes invalid, drawing operations will cause a fatal error.



Table of Contents