iOS Developer Library

Developer

Foundation Framework Reference NSInvocation Class Reference

Options
Deployment Target:

On This Page
Language:

NSInvocation

Inherits From


Conforms To


Import Statement


Not Applicable

Objective-C

@import Foundation;

Availability


Available in iOS 2.0 and later

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.

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

    Declaration

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later

  • selector selector Property

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

    Declaration

    Objective-C

    @property SEL selector

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later

  • target target Property

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

    Declaration

    Objective-C

    @property(assign) id target

    Discussion

    The target is the receiver of the message sent by invoke.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later

  • Sets an argument of the receiver.

    Declaration

    Objective-C

    - (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 target and selector properties. 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.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later

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

    Declaration

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later

  • YEStrue if the receiver has retained its arguments, NOfalse otherwise. (read-only)

    Declaration

    Objective-C

    @property(readonly) BOOL argumentsRetained

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later

  • 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 and blocks.

    Declaration

    Objective-C

    - (void)retainArguments

    Discussion

    Before this method is invoked, argumentsRetained returns NOfalse; after, it returns YEStrue.

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

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later

  • Sets the receiver’s return value.

    Declaration

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later

    See Also

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

  • Gets the receiver's return value.

    Declaration

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later

    See Also

    – setReturnValue:
    – methodReturnType (NSMethodSignature)

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

    Declaration

    Objective-C

    - (void)invoke

    Discussion

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

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later

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

    Declaration

    Objective-C

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

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later

  • The receiver’s method signature. (read-only)

    Declaration

    Objective-C

    @property(readonly, retain) NSMethodSignature *methodSignature

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later