CFMachPort Reference

Overview

A CFMachPort object is a wrapper for a native Mach port (mach_port_t). Mach ports are the native communication channel for the OS X kernel.

CFMachPort does not provide a function to send messages, so you primarily use a CFMachPort object if you need to listen to a Mach port that you obtained by other means. You can get a callback when a message arrives on the port or when the port becomes invalid, such as when the native port dies.

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

To send data, you must use the Mach APIs with the native Mach port, which is not described here. Alternatively, you can use a CFMessagePort Reference object, which can send arbitrary data.

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

Functions by Task

Creating a CFMachPort Object

• CFMachPortCreate
• CFMachPortCreateWithPort

Configuring a CFMachPort Object

• CFMachPortInvalidate
• CFMachPortCreateRunLoopSource
• CFMachPortSetInvalidationCallBack

Examining a CFMachPort Object

• CFMachPortGetContext
• CFMachPortGetInvalidationCallBack
• CFMachPortGetPort
• CFMachPortIsValid

Getting the CFMachPort Type ID

• CFMachPortGetTypeID

Functions

CFMachPortCreate

Creates a CFMachPort object with a new Mach port.

CFMachPortRef CFMachPortCreate (
   CFAllocatorRef allocator,
   CFMachPortCallBack callout,
   CFMachPortContext *context,
   Boolean *shouldFreeInfo
);

CFMachPortCreateRunLoopSource

Creates a CFRunLoopSource object for a CFMachPort object.

CFRunLoopSourceRef CFMachPortCreateRunLoopSource (
   CFAllocatorRef allocator,
   CFMachPortRef port,
   CFIndex order
);

CFMachPortCreateWithPort

Creates a CFMachPort object for a pre-existing native Mach port.

CFMachPortRef CFMachPortCreateWithPort (
   CFAllocatorRef allocator,
   mach_port_t portNum,
   CFMachPortCallBack callout,
   CFMachPortContext *context,
   Boolean *shouldFreeInfo
);

CFMachPortGetContext

Returns the context information for a CFMachPort object.

void CFMachPortGetContext (
   CFMachPortRef port,
   CFMachPortContext *context
);

CFMachPortGetInvalidationCallBack

Returns the invalidation callback function for a CFMachPort object.

CFMachPortInvalidationCallBack CFMachPortGetInvalidationCallBack (
   CFMachPortRef port
);

CFMachPortGetPort

Returns the native Mach port represented by a CFMachPort object.

mach_port_t CFMachPortGetPort (
   CFMachPortRef port
);

CFMachPortGetTypeID

Returns the type identifier for the CFMachPort opaque type.

CFTypeID CFMachPortGetTypeID (
   void
);

CFMachPortInvalidate

Invalidates a CFMachPort object, stopping it from receiving any more messages.

void CFMachPortInvalidate (
   CFMachPortRef port
);

CFMachPortIsValid

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

Boolean CFMachPortIsValid (
   CFMachPortRef port
);

CFMachPortSetInvalidationCallBack

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

void CFMachPortSetInvalidationCallBack (
   CFMachPortRef port,
   CFMachPortInvalidationCallBack callout
);

Callbacks

CFMachPortCallBack

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

typedef void (*CFMachPortCallBack) (
   CFMachPortRef port,
   void *msg,
   CFIndex size,
   void *info
);

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

void MyCallBack (
   CFMachPortRef port,
   void *msg,
   CFIndex size,
   void *info
);

CFMachPortInvalidationCallBack

Callback invoked when a CFMachPort object is invalidated.

typedef void (*CFMachPortInvalidationCallBack) (
   CFMachPortRef port,
   void *info
);

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

void MyCallBack (
   CFMachPortRef port,
   void *info
);

Data Types

CFMachPortContext

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

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

Fields

version

Version number of the structure. Must be 0.

info

An arbitrary pointer to program-defined data, which can be associated with the CFMachPort object 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.

CFMachPortRef

A reference to a CFMachPort object.

typedef struct __CFMachPort *CFMachPortRef;