CFMessagePort Reference

Overview

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 by Task

Creating a CFMessagePort Object

• CFMessagePortCreateLocal
• CFMessagePortCreateRemote

Configuring a CFMessagePort Object

• CFMessagePortCreateRunLoopSource
• CFMessagePortSetInvalidationCallBack
• CFMessagePortSetName

Using a Message Port

• CFMessagePortInvalidate
• CFMessagePortSendRequest
• CFMessagePortSetDispatchQueue

Examining a Message Port

• CFMessagePortGetContext
• CFMessagePortGetInvalidationCallBack
• CFMessagePortGetName
• CFMessagePortIsRemote
• CFMessagePortIsValid

Getting the CFMessagePort Type ID

• CFMessagePortGetTypeID

Functions

CFMessagePortCreateLocal

Returns a local CFMessagePort object.

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

CFMessagePortCreateRemote

Returns a CFMessagePort object connected to a remote port.

CFMessagePortRef CFMessagePortCreateRemote (
   CFAllocatorRef allocator,
   CFStringRef name
);

CFMessagePortCreateRunLoopSource

Creates a CFRunLoopSource object for a CFMessagePort object.

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

CFMessagePortGetContext

Returns the context information for a CFMessagePort object.

void CFMessagePortGetContext (
   CFMessagePortRef ms,
   CFMessagePortContext *context
);

CFMessagePortGetInvalidationCallBack

Returns the invalidation callback function for a CFMessagePort object.

CFMessagePortInvalidationCallBack CFMessagePortGetInvalidationCallBack (
   CFMessagePortRef ms
);

CFMessagePortGetName

Returns the name with which a CFMessagePort object is registered.

CFStringRef CFMessagePortGetName (
   CFMessagePortRef ms
);

CFMessagePortGetTypeID

Returns the type identifier for the CFMessagePort opaque type.

CFTypeID CFMessagePortGetTypeID (
   void
);

CFMessagePortInvalidate

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

void CFMessagePortInvalidate (
   CFMessagePortRef ms
);

CFMessagePortIsRemote

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

Boolean CFMessagePortIsRemote (
   CFMessagePortRef ms
);

CFMessagePortIsValid

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

Boolean CFMessagePortIsValid (
   CFMessagePortRef ms
);

CFMessagePortSendRequest

Sends a message to a remote CFMessagePort object.

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

CFMessagePortSetDispatchQueue

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

void CFMessagePortSetDispatchQueue (
   CFMessagePortRef ms,
   dispatch_queue_t queue
);

CFMessagePortSetInvalidationCallBack

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

void CFMessagePortSetInvalidationCallBack (
   CFMessagePortRef ms,
   CFMessagePortInvalidationCallBack callout
);

CFMessagePortSetName

Sets the name of a local CFMessagePort object.

Boolean CFMessagePortSetName (
   CFMessagePortRef ms,
   CFStringRef newName
);

Callbacks

CFMessagePortCallBack

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

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

If you name your function MyCallBack, you would declare it like this:

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

CFMessagePortInvalidationCallBack

Callback invoked when a CFMessagePort object is invalidated.

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

If you name your function MyCallBack, you would declare it like this:

void MyCallBack (
   CFMessagePortRef ms,
   void *info
);

Data Types

CFMessagePortContext

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

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.

CFMessagePortRef

A reference to a message port object.

typedef struct __CFMessagePort *CFMessagePortRef;

Constants

CFMessagePortSendRequest Error Codes

Error codes for CFMessagePortSendRequest.

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

Constants

kCFMessagePortSuccess

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

Available in OS X v10.0 and later.

Declared in CFMessagePort.h.

kCFMessagePortSendTimeout

The message could not be sent before the send timeout.

Available in OS X v10.0 and later.

Declared in CFMessagePort.h.

kCFMessagePortReceiveTimeout

No reply was received before the receive timeout.

Available in OS X v10.0 and later.

Declared in CFMessagePort.h.

kCFMessagePortIsInvalid

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

Available in OS X v10.0 and later.

Declared in CFMessagePort.h.

kCFMessagePortTransportError

An error occurred trying to send the message.

Available in OS X v10.0 and later.

Declared in CFMessagePort.h.

kCFMessagePortBecameInvalidError

The message port was invalidated.

Available in OS X v10.6 and later.

Declared in CFMessagePort.h.