iOS Developer Library

Developer

Core Foundation 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<DarwinBoolean>) -> 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.

    Availability

    Available in iOS 2.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<DarwinBoolean>) -> 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.

    Availability

    Available in iOS 2.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.

    Availability

    Available in iOS 2.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.

    Availability

    Available in iOS 2.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.

    Availability

    Available in iOS 2.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.

    Availability

    Available in iOS 2.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.

    Availability

    Available in iOS 2.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.

    Availability

    Available in iOS 2.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!) -> Bool

    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.

    Availability

    Available in iOS 2.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.

    Availability

    Available in iOS 2.0 and later.

Callbacks

Data Types

Miscellaneous