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.

• - (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.

• - (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.