Copyright ã1994 by NeXT Computer, Inc.  All Rights Reserved.

NSInvocation 

Inherits From:	NSObject

Conforms To:	NSCoding
NSObject (NSObject)

Declared In:	Foundation/NSInvocation.h 

Class Description

Objects of the NSInvocation class provide a system-independent means to construct message calls to other objects. An NSInvocation object constructs a target object to which a message can be sent, a selector for that method, an argument list for the selector, and a return value. NSInvocation objects provide great flexibility in that the methods, method arguments, and targets of the methods may be constructed dynamically.

The final sending of the message to the target object can be performed at any time, independent of constructing the invocation. For example, methods could be dispatched based on timer events. In addition, return values from the methods are stored in the NSInvocation object and can be retrieved at any later stage in processing.

Also see NSMethodSignature for a description of how to construct method signatures. 

The Foundation/NSInvocation.h header file defines two macros that may be used as constructors for invocations:

NSInvocation *invocation = NS_MESSAGE(target, message)		
	builds an invocation containing a message to a known target object. target is an object id. message consists of a selector followed by any arguments, just like an Objective-C message.

NSInvocation *invocation = NS_INVOCATION(class, message)	
	builds an invocation containing a message to the untargeted class object class. message consists of a selector followed by any arguments, just like an Objective-C message.

Creating Invocations 

+ (NSInvocation *)invocationWithMethodSignature:(NSMethodSignature *)sig
	Returns an invocation object able to construct calls to objects using method selectors with type signatures described by sig. Raises NSInvalidArgumentException if sig is nil.

Managing Invocation Arguments

- (BOOL)argumentsRetained	Returns YES if arguments are retained.

- (void)getArgument:(void *)argumentLocation	Copies the argument stored at index into the storage
atIndex:(int)index		pointed to by argumentLocation where 2 is the index of the first argument, 3 is the index of the second, and so on.

- (void)getReturnValue:(void *)retLoc	Copies the invocation's return value into the storage pointed to by retLoc.

- (NSMethodSignature *)methodSignature	Returns the invocation's method signature object.

- (void)retainArguments	By default, target and arguments are not retained, and C strings are not copied. This method instructs the invocation to retain its arguments, target, and make copies of C strings. This method is invoked automatically by timers. This method should be invoked whenever the dynamic scope of the invocation can exceed its arguments.

- (SEL)selector	Returns the invocation's selector.

- (void)setArgument:(void *)argumentLocation	Sets the argument stored at index to the storage pointed to
atIndex:(int)index		by argumentLocation where 2 is the index of the first argument, 3 is the index of the second, and so on..

- (void)setReturnValue:(void *)retLoc	Sets the invocation's return value to that indicated by retLoc. 

- (void)setSelector:(SEL)selector	Sets the invocation's selector to selector. 

- (void)setTarget:(id)target	Sets the invocation's target to target. 

- (id)target	Returns the invocation's target; returns nil if there is no target.

Dispatching an Invocation

- (void)invoke	Causes the message encoded in the invocation to be dispatched to its target.

- (void)invokeWithTarget:(id)target	Causes the message encoded in the invocation to be dispatched to target.