CFMessagePort Reference

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

Creating a CFMessagePort Object


    
      
           CFMessagePortCreateLocal(_:_:_:_:_:)
      
      
           CFMessagePortCreateLocal

Returns a local CFMessagePort object.

Declaration

Swift

func CFMessagePortCreateLocal(_ allocator: CFAllocator!, _ name: CFString!, _ callout: CFMessagePortCallBack!, _ context: UnsafeMutablePointer<CFMessagePortContext>, _ shouldFreeInfo: UnsafeMutablePointer<DarwinBoolean>) -> 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.

Availability

Available in OS X v10.0 and later.


    
      
           CFMessagePortCreateRemote(_:_:)
      
      
           CFMessagePortCreateRemote

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.

Availability

Available in OS X v10.0 and later.

Configuring a CFMessagePort Object


    
      
           CFMessagePortCreateRunLoopSource(_:_:_:)
      
      
           CFMessagePortCreateRunLoopSource

Creates a CFRunLoopSource object for a CFMessagePort object.

Declaration

Swift

func CFMessagePortCreateRunLoopSource(_ allocator: CFAllocator!, _ local: 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.

Availability

Available in OS X v10.0 and later.

CFMessagePortSetInvalidationCallBack(_:_:) CFMessagePortSetInvalidationCallBack

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.

Availability

Available in OS X v10.0 and later.
CFMessagePortSetName(_:_:) CFMessagePortSetName

Sets the name of a local CFMessagePort object.

Declaration

Swift

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

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.

Availability

Available in OS X v10.0 and later.

Using a Message Port

CFMessagePortInvalidate(_:) CFMessagePortInvalidate

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.

Availability

Available in OS X v10.0 and later.


    
      
           CFMessagePortSendRequest(_:_:_:_:_:_:_:)
      
      
           CFMessagePortSendRequest

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.

Availability

Available in OS X v10.0 and later.

CFMessagePortSetDispatchQueue(_:_:) CFMessagePortSetDispatchQueue

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.

Availability

Available in OS X v10.6 and later.

Examining a Message Port


    
      
           CFMessagePortGetContext(_:_:)
      
      
           CFMessagePortGetContext

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.

Availability

Available in OS X v10.0 and later.

CFMessagePortGetInvalidationCallBack(_:) CFMessagePortGetInvalidationCallBack

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.

Availability

Available in OS X v10.0 and later.
CFMessagePortGetName(_:) CFMessagePortGetName

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.

Availability

Available in OS X v10.0 and later.
CFMessagePortIsRemote(_:) CFMessagePortIsRemote

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

Declaration

Swift

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

Objective-C

Boolean CFMessagePortIsRemote ( CFMessagePortRef ms );

Parameters

ms

The message port to examine.

Return Value

true if ms is a remote port, otherwise false.

Availability

Available in OS X v10.0 and later.
CFMessagePortIsValid(_:) CFMessagePortIsValid

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!) -> Bool

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.

Availability

Available in OS X v10.0 and later.

Getting the CFMessagePort Type ID

CFMessagePortGetTypeID() CFMessagePortGetTypeID

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.

Availability

Available in OS X v10.0 and later.

Callbacks

CFMessagePort Miscellaneous Callbacks


    
      
           CFMessagePortCallBack
      
      
           CFMessagePortCallBack

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

Declaration

Swift

typealias CFMessagePortCallBack = (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.

Availability

Available in OS X v10.0 and later.


    
      
           CFMessagePortInvalidationCallBack
      
      
           CFMessagePortInvalidationCallBack

Callback invoked when a CFMessagePort object is invalidated.

Declaration

Swift

typealias CFMessagePortInvalidationCallBack = (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.

Availability

Available in OS X v10.0 and later.

Data Types

Miscellaneous

CFMessagePortContext

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: ((UnsafePointer<Void>) -> UnsafePointer<Void>)! var release: ((UnsafePointer<Void>) -> Void)! var copyDescription: ((UnsafePointer<Void>) -> Unmanaged<CFString>!)! init() init(version version: CFIndex, info info: UnsafeMutablePointer<Void>, retain retain: ((UnsafePointer<Void>) -> UnsafePointer<Void>)!, release release: ((UnsafePointer<Void>) -> Void)!, copyDescription copyDescription: ((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.
CFMessagePortRef CFMessagePortRef

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

CFMessagePortSendRequest Error Codes
Error codes for CFMessagePortSendRequest.

Declaration

Swift

var kCFMessagePortSuccess: Int32 { get } var kCFMessagePortSendTimeout: Int32 { get } var kCFMessagePortReceiveTimeout: Int32 { get } var kCFMessagePortIsInvalid: Int32 { get } var kCFMessagePortTransportError: Int32 { get } var kCFMessagePortBecameInvalidError: Int32 { 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.

`ms`	The local message port to examine.
`newName`	The new name for `ms`.

`ms`	The message port to schedule.
`queue`	The libdispatch queue.