Mac Developer Library

Developer

CoreFoundation Framework Reference CFMachPort Reference

Options
Deployment Target:

On This Page
Language:

CFMachPort Reference

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

  • Creates a CFMachPort object with a new Mach port.

    Declaration

    Swift

    func CFMachPortCreate(_ allocator: CFAllocator!, _ callout: CFMachPortCallBack, _ context: UnsafeMutablePointer<CFMachPortContext>, _ shouldFreeInfo: UnsafeMutablePointer<Boolean>) -> CFMachPort!

    Objective-C

    CFMachPortRef CFMachPortCreate ( CFAllocatorRef allocator, CFMachPortCallBack callout, CFMachPortContext *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.

    callout

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

    context

    A structure holding contextual information for the new Mach 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, false otherwise. shouldFreeInfo can be NULL.

    Return Value

    The new CFMachPort object or NULL on failure. The CFMachPort object has both send and receive rights. Ownership follows the Create Rule.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func CFMachPortCreateWithPort(_ allocator: CFAllocator!, _ portNum: mach_port_t, _ callout: CFMachPortCallBack, _ context: UnsafeMutablePointer<CFMachPortContext>, _ shouldFreeInfo: UnsafeMutablePointer<Boolean>) -> CFMachPort!

    Objective-C

    CFMachPortRef CFMachPortCreateWithPort ( CFAllocatorRef allocator, mach_port_t portNum, CFMachPortCallBack callout, CFMachPortContext *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.

    portNum

    The native Mach port to use.

    callout

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

    context

    A structure holding contextual information for the Mach 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 CFMachPort object already exists for portNum, false otherwise. shouldFreeInfo can be NULL.

    Return Value

    The new CFMachPort object or NULL on failure. If a CFMachPort object already exists for portNum, the function returns the pre-existing object instead of creating a new object; the context and callout parameters are ignored in this case. Ownership follows the Create Rule.

    Discussion

    The CFMachPort object does not take full ownership of the send and receive rights of the Mach port portNum. It is the caller’s responsibility to deallocate the Mach port rights after the CFMachPort object is no longer needed and has been invalidated.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func CFMachPortInvalidate(_ port: CFMachPort!)

    Objective-C

    void CFMachPortInvalidate ( CFMachPortRef port );

    Parameters

    port

    The CFMachPort object to invalidate.

    Discussion

    Invalidating a CFMachPort object prevents the port from ever receiving any more messages. The CFMachPort object 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 CFMachPortSetInvalidationCallBack. The CFMachPortContext info information for port is also released, if a release callback was specified in the port’s context structure. Finally, if a run loop source was created for port, the run loop source is invalidated, as well.

    If the underlying Mach port is destroyed, the CFMachPort object is automatically invalidated.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Creates a CFRunLoopSource object for a CFMachPort object.

    Declaration

    Swift

    func CFMachPortCreateRunLoopSource(_ allocator: CFAllocator!, _ port: CFMachPort!, _ order: CFIndex) -> CFRunLoopSource!

    Objective-C

    CFRunLoopSourceRef CFMachPortCreateRunLoopSource ( CFAllocatorRef allocator, CFMachPortRef port, 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.

    port

    The Mach port for which to create a CFRunLoopSource object.

    order

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

    Return Value

    The new CFRunLoopSource object for port. 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.

    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 CFMachPort object is invalidated.

    Declaration

    Swift

    func CFMachPortSetInvalidationCallBack(_ port: CFMachPort!, _ callout: CFMachPortInvalidationCallBack)

    Objective-C

    void CFMachPortSetInvalidationCallBack ( CFMachPortRef port, CFMachPortInvalidationCallBack callout );

    Parameters

    port

    The CFMachPort object to modify.

    callout

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

    Discussion

    If port 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.

  • Returns the context information for a CFMachPort object.

    Declaration

    Swift

    func CFMachPortGetContext(_ port: CFMachPort!, _ context: UnsafeMutablePointer<CFMachPortContext>)

    Objective-C

    void CFMachPortGetContext ( CFMachPortRef port, CFMachPortContext *context );

    Parameters

    port

    The CFMachPort object to examine.

    context

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

    Discussion

    The context version number for CFMachPort objects 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 CFMachPort object.

    Declaration

    Swift

    func CFMachPortGetInvalidationCallBack(_ port: CFMachPort!) -> CFMachPortInvalidationCallBack

    Objective-C

    CFMachPortInvalidationCallBack CFMachPortGetInvalidationCallBack ( CFMachPortRef port );

    Parameters

    port

    The CFMachPort object to examine.

    Return Value

    The callback function invoked when port is invalidated. NULL if no callback has been set with CFMachPortSetInvalidationCallBack.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the native Mach port represented by a CFMachPort object.

    Declaration

    Swift

    func CFMachPortGetPort(_ port: CFMachPort!) -> mach_port_t

    Objective-C

    mach_port_t CFMachPortGetPort ( CFMachPortRef port );

    Parameters

    port

    The CFMachPort object to examine.

    Return Value

    The native Mach port represented by port.

    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 CFMachPort object is valid and able to receive messages.

    Declaration

    Swift

    func CFMachPortIsValid(_ port: CFMachPort!) -> Boolean

    Objective-C

    Boolean CFMachPortIsValid ( CFMachPortRef port );

    Parameters

    port

    The CFMachPort object to examine.

    Return Value

    true if port 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 CFMachPort opaque type.

    Declaration

    Swift

    func CFMachPortGetTypeID() -> CFTypeID

    Objective-C

    CFTypeID CFMachPortGetTypeID ( void );

    Return Value

    The type identifier for the CFMachPort 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 CFMachPort object.

    Declaration

    Swift

    typealias CFMachPortCallBack = CFunctionPointer<((CFMachPort!, UnsafeMutablePointer<Void>, CFIndex, UnsafeMutablePointer<Void>) -> Void)>

    Objective-C

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

    Parameters

    port

    The CFMachPort object on which the message msg was received.

    msg

    The Mach message received on port. The pointer is to a mach_msg_header_t structure.

    size

    Size of the Mach message msg, excluding the message trailer.

    info

    The info member of the CFMachPortContext structure used when creating port.

    Discussion

    You specify this callback when creating a CFMachPort object with either CFMachPortCreate or CFMachPortCreateWithPort. To receive messages on a CFMachPort object (and have this callback invoked), you must create a run loop source for the port and add it to a run loop.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Callback invoked when a CFMachPort object is invalidated.

    Declaration

    Swift

    typealias CFMachPortInvalidationCallBack = CFunctionPointer<((CFMachPort!, UnsafeMutablePointer<Void>) -> Void)>

    Objective-C

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

    Parameters

    port

    The CFMachPort object that has been invalidated.

    info

    The info member of the CFMachPortContext structure used when creating port.

    Discussion

    Your callback should free any resources allocated for port.

    You specify this callback with CFMachPortSetInvalidationCallBack.

    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 CFMachPort object’s behavior.

    Declaration

    Swift

    struct CFMachPortContext { 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>!)> }

    Objective-C

    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.

    Availability

    Available in OS X v10.0 and later.

  • A reference to a CFMachPort object.

    Declaration

    Swift

    typealias CFMachPortRef = CFMachPort

    Objective-C

    typedef struct __CFMachPort *CFMachPortRef;

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.