NSInvocation Class Reference

Inherits from
NSObject
Conforms to
NSObject (NSObject)
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in iOS 2.0 and later.
Companion guide
Distributed Objects Programming Topics
Declared in
NSInvocation.h
Related sample code

Overview

An NSInvocation is an Objective-C message rendered static, that is, it is an action turned into an object. NSInvocation objects are used to store and forward messages between objects and between applications, primarily by NSTimer objects and the distributed objects system.

An NSInvocation object contains all the elements of an Objective-C message: a target, a selector, arguments, and the return value. Each of these elements can be set directly, and the return value is set automatically when the NSInvocation object is dispatched.

An NSInvocation object can be repeatedly dispatched to different targets; its arguments can be modified between dispatch for varying results; even its selector can be changed to another with the same method signature (argument and return types). This flexibility makes NSInvocation useful for repeating messages with many arguments and variations; rather than retyping a slightly different expression for each message, you modify the NSInvocation object as needed each time before dispatching it to a new target.

NSInvocation does not support invocations of methods with either variable numbers of arguments or union arguments. You should use the invocationWithMethodSignature: class method to create NSInvocation objects; you should not create these objects using alloc and init.

This class does not retain the arguments for the contained invocation by default. If those objects might disappear between the time you create your instance of NSInvocation and the time you use it, you should explicitly retain the objects yourself or invoke the retainArguments method to have the invocation object retain them itself.

Adopted Protocols

NSCoding

Tasks

Creating NSInvocation Objects

Configuring an Invocation Object

Dispatching an Invocation

Getting the Method Signature

Class Methods

invocationWithMethodSignature:

Returns an NSInvocation object able to construct messages using a given method signature.

+ (NSInvocation *)invocationWithMethodSignature:(NSMethodSignature *)signature
Parameters
signature

An object encapsulating a method signature.

Discussion

The new object must have its selector set with setSelector: and its arguments set with setArgument:atIndex: before it can be invoked. Do not use the alloc/init approach to create NSInvocation objects.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
NSInvocation.h

Instance Methods

argumentsRetained

Returns YES if the receiver has retained its arguments, NO otherwise.

- (BOOL)argumentsRetained
Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
NSInvocation.h

getArgument:atIndex:

Returns by indirection the receiver's argument at a specified index.

- (void)getArgument:(void *)buffer atIndex:(NSInteger)index
Parameters
buffer

An untyped buffer to hold the returned argument. See the discussion below relating to argument values that are objects.

index

An integer specifying the index of the argument to get.

Indices 0 and 1 indicate the hidden arguments self and _cmd, respectively; these values can be retrieved directly with the target and selector methods. Use indices 2 and greater for the arguments normally passed in a message.

Discussion

This method copies the argument stored at index into the storage pointed to by buffer. The size of buffer must be large enough to accommodate the argument value.

When the argument value is an object, pass a pointer to the variable (or memory) into which the object should be placed:

NSArray *anArray;
[invocation getArgument:&anArray atIndex:3];

This method raises NSInvalidArgumentException if index is greater than the actual number of arguments for the selector.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
NSInvocation.h

getReturnValue:

Gets the receiver's return value.

- (void)getReturnValue:(void *)buffer
Parameters
buffer

An untyped buffer into which the receiver copies its return value. It should be large enough to accommodate the value. See the discussion below for more information about buffer.

Discussion

Use the NSMethodSignature method methodReturnLength to determine the size needed for buffer:

NSUInteger length = [[myInvocation methodSignature] methodReturnLength];
buffer = (void *)malloc(length);
[invocation getReturnValue:buffer];

When the return value is an object, pass a pointer to the variable (or memory) into which the object should be placed:

id anObject;
NSArray *anArray;
[invocation1 getReturnValue:&anObject];
[invocation2 getReturnValue:&anArray];

If the NSInvocation object has never been invoked, the result of this method is undefined.

Availability
  • Available in iOS 2.0 and later.
See Also
Related Sample Code
Declared In
NSInvocation.h

invoke

Sends the receiver’s message (with arguments) to its target and sets the return value.

- (void)invoke
Discussion

You must set the receiver’s target, selector, and argument values before calling this method.

Availability
  • Available in iOS 2.0 and later.
See Also
Related Sample Code
Declared In
NSInvocation.h

invokeWithTarget:

Sets the receiver’s target, sends the receiver’s message (with arguments) to that target, and sets the return value.

- (void)invokeWithTarget:(id)anObject
Parameters
anObject

The object to set as the receiver's target.

Discussion

You must set the receiver’s selector and argument values before calling this method.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
NSInvocation.h

methodSignature

Returns the receiver’s method signature.

- (NSMethodSignature *)methodSignature
Availability
  • Available in iOS 2.0 and later.
Declared In
NSInvocation.h

retainArguments

If the receiver hasn’t already done so, retains the target and all object arguments of the receiver and copies all of its C-string arguments.

- (void)retainArguments
Discussion

Before this method is invoked, argumentsRetained returns NO; after, it returns YES.

For efficiency, newly created NSInvocations don’t retain or copy their arguments, nor do they retain their targets or copy C strings. You should instruct an NSInvocation to retain its arguments if you intend to cache it, since the arguments may otherwise be released before the NSInvocation is invoked. NSTimers always instruct their NSInvocations to retain their arguments, for example, because there’s usually a delay before an NSTimer fires.

Availability
  • Available in iOS 2.0 and later.
Declared In
NSInvocation.h

selector

Returns the receiver’s selector, or 0 if it hasn’t been set.

- (SEL)selector
Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
NSInvocation.h

setArgument:atIndex:

Sets an argument of the receiver.

- (void)setArgument:(void *)buffer atIndex:(NSInteger)index
Parameters
buffer

An untyped buffer containing an argument to be assigned to the receiver. See the discussion below relating to argument values that are objects.

index

An integer specifying the index of the argument.

Indices 0 and 1 indicate the hidden arguments self and _cmd, respectively; you should set these values directly with the setTarget: and setSelector: methods. Use indices 2 and greater for the arguments normally passed in a message.

Discussion

This method copies the contents of buffer as the argument at index. The number of bytes copied is determined by the argument size.

When the argument value is an object, pass a pointer to the variable (or memory) from which the object should be copied:

NSArray *anArray;
[invocation setArgument:&anArray atIndex:3];

This method raises NSInvalidArgumentException if the value of index is greater than the actual number of arguments for the selector.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
NSInvocation.h

setReturnValue:

Sets the receiver’s return value.

- (void)setReturnValue:(void *)buffer
Parameters
buffer

An untyped buffer whose contents are copied as the receiver's return value.

Discussion

This value is normally set when you send an invoke or invokeWithTarget: message.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
NSInvocation.h

setSelector:

Sets the receiver’s selector.

- (void)setSelector:(SEL)selector
Parameters
selector

The selector to assign to the receiver.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
NSInvocation.h

setTarget:

Sets the receiver’s target.

- (void)setTarget:(id)anObject
Parameters
anObject

The object to assign to the receiver as target. The target is the receiver of the message sent by invoke.

Discussion

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
NSInvocation.h

target

Returns the receiver’s target, or nil if the receiver has no target.

- (id)target
Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
NSInvocation.h


© 2009 Apple Inc. All Rights Reserved. (Last updated: 2009-07-04)

Did this document help you? Yes It's good, but... Not helpful...