Next Page > Hide TOC

NSInvocation Class Reference

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

• – encodeWithCoder:

• – initWithCoder:

Tasks

Creating NSInvocation Objects

• + invocationWithMethodSignature:

Configuring an Invocation Object

• – setSelector:
• – selector
• – setTarget:
• – target
• – setArgument:atIndex:
• – getArgument:atIndex:
• – argumentsRetained
• – retainArguments
• – setReturnValue:
• – getReturnValue:

Dispatching an Invocation

• – invoke
• – invokeWithTarget:

Getting the Method Signature

• – methodSignature

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 Mac OS X v10.0 and later.

Related Sample Code

• CubePuzzle
• DeskPictAppDockMenu

Declared In

Instance Methods

argumentsRetained

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

- (BOOL)argumentsRetained

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – retainArguments

Declared In

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 Mac OS X v10.0 and later.

See Also

• – setArgument:atIndex:
• – numberOfArguments (NSMethodSignature)

Declared In

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 Mac OS X v10.0 and later.

See Also

• – setReturnValue:
• – methodReturnType (NSMethodSignature)

Related Sample Code

• CubePuzzle

Declared In

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 Mac OS X v10.0 and later.

See Also

• – getReturnValue:
• – setSelector:
• – setTarget:
• – setArgument:atIndex:

Related Sample Code

• CubePuzzle

Declared In

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 Mac OS X v10.0 and later.

See Also

• – getReturnValue:
• – invoke
• – setSelector:
• – setTarget:
• – setArgument:atIndex:

Declared In

methodSignature

Returns the receiver’s method signature.

- (NSMethodSignature *)methodSignature

Availability

• Available in Mac OS X v10.0 and later.

Declared In

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 Mac OS X v10.0 and later.

Declared In

selector

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

- (SEL)selector

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setSelector:

Declared In

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 Mac OS X v10.0 and later.

See Also

• – getArgument:atIndex:
• – numberOfArguments (NSMethodSignature)

Related Sample Code

• CubePuzzle
• DeskPictAppDockMenu

Declared In

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 Mac OS X v10.0 and later.

See Also

• – getReturnValue:
• – methodReturnLength (NSMethodSignature)
• – methodReturnType (NSMethodSignature)

Declared In

setSelector:

Sets the receiver’s selector.

- (void)setSelector:(SEL)selector

Parameters

selector

The selector to assign to the receiver.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – selector

Related Sample Code

• CubePuzzle
• DeskPictAppDockMenu

Declared In

setTarget:

Sets the receiver’s targe.

- (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 Mac OS X v10.0 and later.

See Also

• – target
• – invokeWithTarget:

Related Sample Code

• CubePuzzle
• DeskPictAppDockMenu

Declared In

target

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

- (id)target

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setTarget:

Declared In

Constants

Parameter Type Constants

Method argument types. (Deprecated. These constants are used internally by NSInvocation—you should not use them directly.)

enum _NSObjCValueType {
   NSObjCNoType = 0,
   NSObjCVoidType = 'v',
   NSObjCCharType = 'c',
   NSObjCShortType = 's',
   NSObjCLongType = 'l',
   NSObjCLonglongType = 'q',
   NSObjCFloatType = 'f',
   NSObjCDoubleType = 'd',
   
   NSObjCBoolType = 'B',
   
   NSObjCSelectorType = ':',
   NSObjCObjectType = '@',
   NSObjCStructType = '{',
   NSObjCPointerType = '^',
   NSObjCStringType = '*',
   NSObjCArrayType = '[',
   NSObjCUnionType = '(',
   NSObjCBitfield = 'b'
};

Constants

NSObjCNoType

No type information. (Deprecated. Used internally by NSInvocation—do not use it directly)

Available in Mac OS X v10.0 and later.

Declared in NSInvocation.h.

NSObjCVoidType

The void type. (Deprecated. Used internally by NSInvocation—do not use it directly)

Available in Mac OS X v10.0 and later.

Declared in NSInvocation.h.

NSObjCCharType

The char type. (Deprecated. Used internally by NSInvocation—do not use it directly)

Available in Mac OS X v10.0 and later.

Declared in NSInvocation.h.

NSObjCShortType

The short integer type. (Deprecated. Used internally by NSInvocation—do not use it directly)

Available in Mac OS X v10.0 and later.

Declared in NSInvocation.h.

NSObjCLongType

The long integer type. (Deprecated. Used internally by NSInvocation—do not use it directly)

Available in Mac OS X v10.0 and later.

Declared in NSInvocation.h.

NSObjCLonglongType

The long long integer type. (Deprecated. Used internally by NSInvocation—do not use it directly)

Available in Mac OS X v10.0 and later.

Declared in NSInvocation.h.

NSObjCFloatType

The float type. (Deprecated. Used internally by NSInvocation—do not use it directly)

Available in Mac OS X v10.0 and later.

Declared in NSInvocation.h.

NSObjCDoubleType

The double type. (Deprecated. Used internally by NSInvocation—do not use it directly)

Available in Mac OS X v10.0 and later.

Declared in NSInvocation.h.

NSObjCBoolType

The BOOL type. (Deprecated. Used internally by NSInvocation—do not use it directly)

Available in Mac OS X v10.2 and later.

Declared in NSInvocation.h.

NSObjCSelectorType

The SEL type. (Deprecated. Used internally by NSInvocation—do not use it directly)

Available in Mac OS X v10.0 and later.

Declared in NSInvocation.h.

NSObjCObjectType

The id type. (Deprecated. Used internally by NSInvocation—do not use it directly)

Available in Mac OS X v10.0 and later.

Declared in NSInvocation.h.

NSObjCStructType

The struct type. (Deprecated. Used internally by NSInvocation—do not use it directly)

Available in Mac OS X v10.0 and later.

Declared in NSInvocation.h.

NSObjCPointerType

The void* type. (Deprecated. Used internally by NSInvocation—do not use it directly)

Available in Mac OS X v10.0 and later.

Declared in NSInvocation.h.

NSObjCStringType

The char* type. (Deprecated. Used internally by NSInvocation—do not use it directly)

Available in Mac OS X v10.0 and later.

Declared in NSInvocation.h.

NSObjCArrayType

A C-style array of items. (Deprecated. Used internally by NSInvocation—do not use it directly)

Available in Mac OS X v10.0 and later.

Declared in NSInvocation.h.

NSObjCUnionType

A union union type. (Deprecated. Used internally by NSInvocation—do not use it directly)

Available in Mac OS X v10.0 and later.

Declared in NSInvocation.h.

NSObjCBitfield

A bit field. (Deprecated. Used internally by NSInvocation—do not use it directly)

Available in Mac OS X v10.0 and later.

Declared in NSInvocation.h.

Declared In

Next Page > Hide TOC