Mac Developer Library

Developer

CoreFoundation Framework Reference CFMessagePort Reference

Options
Deployment Target:

On This Page
Language:

CFMessagePort Reference

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Swift

import CoreFoundation

Objective-C

@import CoreFoundation;

CFMessagePort objects provide a communications channel that can transmit arbitrary data between multiple threads or processes on the local machine.

You create a local message port with CFMessagePortCreateLocal and make it available to other processes by giving it a name, either when you create it or later with CFMessagePortSetName. Other processes then connect to it using CFMessagePortCreateRemote, specifying the name of the port.

To listen for messages, you need to create a run loop source with CFMessagePortCreateRunLoopSource and add it to a run loop with CFRunLoopAddSource.

Your message port’s callback function will be called when a message arrives. To send data, you store the data in a CFData object and call CFMessagePortSendRequest. You can optionally have the function wait for a reply and return the reply in another CFData object.

Message ports only support communication on the local machine. For network communication, you have to use a CFSocket object.

Functions

  • Returns a local CFMessagePort object.

    Declaration

    Swift

    func CFMessagePortCreateLocal(_ allocator: CFAllocator!, _ name: CFString!, _ callout: CFMessagePortCallBack, _ context: UnsafeMutablePointer<CFMessagePortContext>, _ shouldFreeInfo: UnsafeMutablePointer<Boolean>) -> CFMessagePort!

    Objective-C

    CFMessagePortRef CFMessagePortCreateLocal ( CFAllocatorRef allocator, CFStringRef name, CFMessagePortCallBack callout, CFMessagePortContext *context, Boolean *shouldFreeInfo );

    Parameters

    allocator

    The allocator to use to allocate memory for the new object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

    name

    The name with which to register the port. name can be NULL.

    callout

    The callback function invoked when a message is received on the message port.

    context

    A structure holding contextual information for the message port. The function copies the information out of the structure, so the memory pointed to by context does not need to persist beyond the function call.

    shouldFreeInfo

    A flag set by the function to indicate whether the info member of context should be freed. The flag is set to true on failure or if a local port named name already exists, false otherwise. shouldFreeInfo can be NULL.

    Return Value

    The new CFMessagePort object, or NULL on failure. If a local port is already named name, the function returns that port instead of creating a new object; the context and callout parameters are ignored in this case. Ownership follows the Create Rule.

    Special Considerations

    This method is not available on iOS 7 and later—it will return NULL and log a sandbox violation in syslog. See Concurrency Programming Guide for possible replacement technologies.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Returns a CFMessagePort object connected to a remote port.

    Declaration

    Swift

    func CFMessagePortCreateRemote(_ allocator: CFAllocator!, _ name: CFString!) -> CFMessagePort!

    Objective-C

    CFMessagePortRef CFMessagePortCreateRemote ( CFAllocatorRef allocator, CFStringRef name );

    Parameters

    allocator

    The allocator to use to allocate memory for the new object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

    name

    The name of the remote message port to which to connect.

    Return Value

    The new CFMessagePort object, or NULL on failure. If a message port has already been created for the remote port, the pre-existing object is returned. Ownership follows the Create Rule.

    Special Considerations

    This method is not available on iOS 7 and later—it will return NULL and log a sandbox violation in syslog. See Concurrency Programming Guide for possible replacement technologies.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Creates a CFRunLoopSource object for a CFMessagePort object.

    Declaration

    Swift

    func CFMessagePortCreateRunLoopSource(_ allocator: CFAllocator!, _ ms: CFMessagePort!, _ order: CFIndex) -> CFRunLoopSource!

    Objective-C

    CFRunLoopSourceRef CFMessagePortCreateRunLoopSource ( CFAllocatorRef allocator, CFMessagePortRef local, CFIndex order );

    Parameters

    allocator

    The allocator to use to allocate memory for the new object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

    ms

    The message port for which to create a run loop source.

    order

    A priority index indicating the order in which run loop sources are processed. order is currently ignored by CFMessagePort object run loop sources. Pass 0 for this value.

    Return Value

    The new CFRunLoopSource object for ms. Ownership follows the Create Rule.

    Discussion

    The run loop source is not automatically added to a run loop. To add the source to a run loop, use CFRunLoopAddSource.

    Special Considerations

    This method is not available on iOS 7 and later—it will return NULL and log a sandbox violation in syslog. See Concurrency Programming Guide for possible replacement technologies.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Sets the callback function invoked when a CFMessagePort object is invalidated.

    Declaration

    Swift

    func CFMessagePortSetInvalidationCallBack(_ ms: CFMessagePort!, _ callout: CFMessagePortInvalidationCallBack)

    Objective-C

    void CFMessagePortSetInvalidationCallBack ( CFMessagePortRef ms, CFMessagePortInvalidationCallBack callout );

    Parameters

    ms

    The message port to examine.

    callout

    The callback function to invoke when ms is invalidated. Pass NULL to remove a callback.

    Discussion

    If ms is already invalid, callout is invoked immediately.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Sets the name of a local CFMessagePort object.

    Declaration

    Swift

    func CFMessagePortSetName(_ ms: CFMessagePort!, _ newName: CFString!) -> Boolean

    Objective-C

    Boolean CFMessagePortSetName ( CFMessagePortRef ms, CFStringRef newName );

    Parameters

    ms

    The local message port to examine.

    newName

    The new name for ms.

    Return Value

    true if the name change succeeds, otherwise false.

    Discussion

    Other threads and processes can connect to a named message port with CFMessagePortCreateRemote.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Invalidates a CFMessagePort object, stopping it from receiving or sending any more messages.

    Declaration

    Swift

    func CFMessagePortInvalidate(_ ms: CFMessagePort!)

    Objective-C

    void CFMessagePortInvalidate ( CFMessagePortRef ms );

    Parameters

    ms

    The message port to invalidate.

    Discussion

    Invalidating a message port prevents the port from ever sending or receiving any more messages; the message port is not deallocated, though. If the port has not already been invalidated, the port’s invalidation callback function is invoked, if one has been set with CFMessagePortSetInvalidationCallBack. The CFMessagePortContext info information for ms is also released, if a release callback was specified in the port’s context structure. Finally, if a run loop source was created for ms, the run loop source is also invalidated.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Sends a message to a remote CFMessagePort object.

    Declaration

    Swift

    func CFMessagePortSendRequest(_ remote: CFMessagePort!, _ msgid: Int32, _ data: CFData!, _ sendTimeout: CFTimeInterval, _ rcvTimeout: CFTimeInterval, _ replyMode: CFString!, _ returnData: UnsafeMutablePointer<Unmanaged<CFData>?>) -> Int32

    Objective-C

    SInt32 CFMessagePortSendRequest ( CFMessagePortRef remote, SInt32 msgid, CFDataRef data, CFTimeInterval sendTimeout, CFTimeInterval rcvTimeout, CFStringRef replyMode, CFDataRef *returnData );

    Parameters

    remote

    The message port to which data should be sent.

    msgid

    An arbitrary integer value that you can send with the message.

    data

    The data to send to remote.

    sendTimeout

    The time to wait for data to be sent.

    rcvTimeout

    The time to wait for a reply to be returned.

    replyMode

    The run loop mode in which the function should wait for a reply. If the message is a oneway (so no response is expected), then replyMode should be NULL. If replyMode is non-NULL, the function runs the run loop waiting for a reply, in that mode. replyMode can be any string name of a run loop mode, but it should be one with input sources installed. You should use the kCFRunLoopDefaultMode constant unless you have a specific reason to use a different mode.

    returnData

    Upon return, contains a CFData object containing the reply data. Ownership follows the Create Rule.

    Return Value

    Error code indicating success or failure. See CFMessagePortSendRequest Error Codes for the possible return values.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Schedules callbacks for the specified message port on the specified dispatch queue.

    Declaration

    Swift

    func CFMessagePortSetDispatchQueue(_ ms: CFMessagePort!, _ queue: dispatch_queue_t!)

    Objective-C

    void CFMessagePortSetDispatchQueue ( CFMessagePortRef ms, dispatch_queue_t queue );

    Parameters

    ms

    The message port to schedule.

    queue

    The libdispatch queue.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.6 and later.

  • Returns the context information for a CFMessagePort object.

    Declaration

    Swift

    func CFMessagePortGetContext(_ ms: CFMessagePort!, _ context: UnsafeMutablePointer<CFMessagePortContext>)

    Objective-C

    void CFMessagePortGetContext ( CFMessagePortRef ms, CFMessagePortContext *context );

    Parameters

    ms

    The message port to examine.

    context

    A pointer to the structure into which the context information for ms is to be copied. The information being returned is usually the same information you passed to CFMessagePortCreateLocal when creating ms. However, if CFMessagePortCreateLocal returned a cached object instead of creating a new object, context is filled with information from the original message port instead of the information you passed to the function.

    Discussion

    The context version number for message ports is currently 0. Before calling this function, you need to initialize the version member of context to 0.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the invalidation callback function for a CFMessagePort object.

    Declaration

    Swift

    func CFMessagePortGetInvalidationCallBack(_ ms: CFMessagePort!) -> CFMessagePortInvalidationCallBack

    Objective-C

    CFMessagePortInvalidationCallBack CFMessagePortGetInvalidationCallBack ( CFMessagePortRef ms );

    Parameters

    ms

    The message port to examine.

    Return Value

    The callback function invoked when ms is invalidated. NULL if no callback has been set with CFMessagePortSetInvalidationCallBack.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the name with which a CFMessagePort object is registered.

    Declaration

    Swift

    func CFMessagePortGetName(_ ms: CFMessagePort!) -> CFString!

    Objective-C

    CFStringRef CFMessagePortGetName ( CFMessagePortRef ms );

    Parameters

    ms

    The message port to examine.

    Return Value

    The registered name of ms, NULL if unnamed. Ownership follows the Get Rule.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Returns a Boolean value that indicates whether a CFMessagePort object represents a remote port.

    Declaration

    Swift

    func CFMessagePortIsRemote(_ ms: CFMessagePort!) -> Boolean

    Objective-C

    Boolean CFMessagePortIsRemote ( CFMessagePortRef ms );

    Parameters

    ms

    The message port to examine.

    Return Value

    true if ms is a remote port, otherwise false.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Returns a Boolean value that indicates whether a CFMessagePort object is valid and able to send or receive messages.

    Declaration

    Swift

    func CFMessagePortIsValid(_ ms: CFMessagePort!) -> Boolean

    Objective-C

    Boolean CFMessagePortIsValid ( CFMessagePortRef ms );

    Parameters

    ms

    The message port to examine.

    Return Value

    true if ms can be used for communication, otherwise false.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the type identifier for the CFMessagePort opaque type.

    Declaration

    Swift

    func CFMessagePortGetTypeID() -> CFTypeID

    Objective-C

    CFTypeID CFMessagePortGetTypeID ( void );

    Return Value

    The type identifier for the CFMessagePort opaque type.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

Callbacks

  • Callback invoked to process a message received on a CFMessagePort object.

    Declaration

    Swift

    typealias CFMessagePortCallBack = CFunctionPointer<((CFMessagePort!, Int32, CFData!, UnsafeMutablePointer<Void>) -> Unmanaged<CFData>!)>

    Objective-C

    typedef CFDataRef (*CFMessagePortCallBack) ( CFMessagePortRef local, SInt32 msgid, CFDataRef data, void *info );

    Parameters

    local

    The local message port that received the message.

    msgid

    An arbitrary integer value assigned to the message by the sender.

    data

    The message data.

    info

    The info member of the CFMessagePortContext structure that was used when creating local.

    Return Value

    Data to send back to the sender of the message. The system releases the returned CFData object. Return NULL if you want an empty reply returned to the sender.

    Discussion

    If you want the message data to persist beyond this callback, you must explicitly create a copy of data rather than merely retain it; the contents of data will be deallocated after the callback exits.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Callback invoked when a CFMessagePort object is invalidated.

    Declaration

    Swift

    typealias CFMessagePortInvalidationCallBack = CFunctionPointer<((CFMessagePort!, UnsafeMutablePointer<Void>) -> Void)>

    Objective-C

    typedef void (*CFMessagePortInvalidationCallBack) ( CFMessagePortRef ms, void *info );

    Parameters

    ms

    The message port that has been invalidated.

    info

    The info member of the CFMessagePortContext structure that was used when creating ms, if ms is a local port; NULL if ms is a remote port.

    Discussion

    Your callback should free any resources allocated for ms.

    You specify this callback with CFMessagePortSetInvalidationCallBack.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

Data Types

Miscellaneous

  • A structure that contains program-defined data and callbacks with which you can configure a CFMessagePort object’s behavior.

    Declaration

    Swift

    struct CFMessagePortContext { var version: CFIndex var info: UnsafeMutablePointer<Void> var retain: CFunctionPointer<((UnsafePointer<Void>) -> UnsafePointer<Void>)> var release: CFunctionPointer<((UnsafePointer<Void>) -> Void)> var copyDescription: CFunctionPointer<((UnsafePointer<Void>) -> Unmanaged<CFString>!)> init() init(version version: CFIndex, info info: UnsafeMutablePointer<Void>, retain retain: CFunctionPointer<((UnsafePointer<Void>) -> UnsafePointer<Void>)>, release release: CFunctionPointer<((UnsafePointer<Void>) -> Void)>, copyDescription copyDescription: CFunctionPointer<((UnsafePointer<Void>) -> Unmanaged<CFString>!)>) }

    Objective-C

    struct CFMessagePortContext { CFIndex version; void *info; CFAllocatorRetainCallBack retain; CFAllocatorReleaseCallBack release; CFAllocatorCopyDescriptionCallBack copyDescription; }; typedef struct CFMessagePortContext CFMessagePortContext;

    Fields

    version

    Version number of the structure. Must be 0.

    info

    An arbitrary pointer to program-defined data, which can be associated with the message port at creation time. This pointer is passed to all the callbacks defined in the context.

    retain

    A retain callback for your program-defined info pointer. Can be NULL.

    release

    A release callback for your program-defined info pointer. Can be NULL.

    copyDescription

    A copy description callback for your program-defined info pointer. Can be NULL.

    Availability

    Available in OS X v10.0 and later.

  • A reference to a message port object.

    Declaration

    Swift

    typealias CFMessagePortRef = CFMessagePort

    Objective-C

    typedef struct __CFMessagePort *CFMessagePortRef;

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

Constants

Miscellaneous

  • Error codes for CFMessagePortSendRequest.

    Declaration

    Swift

    var kCFMessagePortSuccess: Int { get } var kCFMessagePortSendTimeout: Int { get } var kCFMessagePortReceiveTimeout: Int { get } var kCFMessagePortIsInvalid: Int { get } var kCFMessagePortTransportError: Int { get } var kCFMessagePortBecameInvalidError: Int { get }

    Objective-C

    enum { kCFMessagePortSuccess = 0, kCFMessagePortSendTimeout = -1, kCFMessagePortReceiveTimeout = -2, kCFMessagePortIsInvalid = -3, kCFMessagePortTransportError = -4 kCFMessagePortBecameInvalidError = -5 };

    Constants

    • kCFMessagePortSuccess

      kCFMessagePortSuccess

      The message was successfully sent and, if a reply was expected, a reply was received.

      Available in OS X v10.0 and later.

    • kCFMessagePortSendTimeout

      kCFMessagePortSendTimeout

      The message could not be sent before the send timeout.

      Available in OS X v10.0 and later.

    • kCFMessagePortReceiveTimeout

      kCFMessagePortReceiveTimeout

      No reply was received before the receive timeout.

      Available in OS X v10.0 and later.

    • kCFMessagePortIsInvalid

      kCFMessagePortIsInvalid

      The message could not be sent because the message port is invalid.

      Available in OS X v10.0 and later.

    • kCFMessagePortTransportError

      kCFMessagePortTransportError

      An error occurred trying to send the message.

      Available in OS X v10.0 and later.

    • kCFMessagePortBecameInvalidError

      kCFMessagePortBecameInvalidError

      The message port was invalidated.

      Available in OS X v10.6 and later.