Struct CMBlockBuffer 

pub struct CMBlockBuffer { /* private fields */ }

Available on crate feature CMBlockBuffer only.

A reference to a CMBlockBuffer, a CF object that adheres to retain/release semantics. When CFRelease() is performed on the last reference to the CMBlockBuffer, any referenced BlockBuffers are released and eligible memory blocks are deallocated. These operations are recursive, so one release could result in many follow on releses.

See also Apple’s documentation

Implementations

impl CMBlockBuffer

pub unsafe fn create_empty( structure_allocator: Option<&CFAllocator>, sub_block_capacity: u32, flags: CMBlockBufferFlags, block_buffer_out: NonNull<*mut CMBlockBuffer>, ) -> i32

Creates an empty CMBlockBuffer

Creates an empty CMBlockBuffer, i.e. one which has no memory block nor reference to a CMBlockBuffer supplying bytes to it. It is ready to be populated using CMBlockBufferAppendMemoryBlock() and/or CMBlockBufferAppendBufferReference(). CMBlockBufferGetDataLength() will return zero for an empty CMBlockBuffer and CMBlockBufferGetDataPointer() and CMBlockBufferAssureBufferMemory() will fail. The memory for the CMBlockBuffer object will be allocated using the given allocator. If NULL is passed for the allocator, the default allocator is used.

Parameter structureAllocator: Allocator to use for allocating the CMBlockBuffer object. NULL will cause the default allocator to be used.

Parameter subBlockCapacity: Number of subBlocks the newBlockBuffer shall accommodate before expansion occurs. A value of zero means “do the reasonable default”

Parameter flags: Feature and control flags

Parameter blockBufferOut: Receives newly-created empty CMBlockBuffer object with retain count of 1. Must not be NULL.

Returns: Returns kCMBlockBufferNoErr if successful.

Safety

block_buffer_out must be a valid pointer.

pub unsafe fn create_with_memory_block( structure_allocator: Option<&CFAllocator>, memory_block: *mut c_void, block_length: usize, block_allocator: Option<&CFAllocator>, custom_block_source: *const CMBlockBufferCustomBlockSource, offset_to_data: usize, data_length: usize, flags: CMBlockBufferFlags, block_buffer_out: NonNull<*mut CMBlockBuffer>, ) -> i32

Creates a new CMBlockBuffer backed by a memory block (or promise thereof).

Creates a new CMBlockBuffer backed by a memory block. The memory block may be statically allocated, dynamically allocated using the given allocator (or customBlockSource) or not yet allocated. The returned CMBlockBuffer may be further expanded using CMBlockBufferAppendMemoryBlock() and/or CMBlockBufferAppendBufferReference().

If the kCMBlockBufferAssureMemoryNowFlag is set in the flags parameter, the memory block is allocated immediately using the blockAllocator or customBlockSource.

Parameter structureAllocator: Allocator to use for allocating the CMBlockBuffer object. NULL will cause the default allocator to be used.

Parameter memoryBlock: Block of memory to hold buffered data. If NULL, a memory block will be allocated when needed (via a call to CMBlockBufferAssureBlockMemory()) using the provided blockAllocator or customBlockSource. If non-NULL, the block will be used and will be deallocated when the new CMBlockBuffer is finalized (i.e. released for the last time).

Parameter blockLength: Overall length of the memory block in bytes. Must not be zero. This is the size of the supplied memory block or the size to allocate if memoryBlock is NULL.

Parameter blockAllocator: Allocator to be used for allocating the memoryBlock, if memoryBlock is NULL. If memoryBlock is non-NULL, this allocator will be used to deallocate it if provided. Passing NULL will cause the default allocator (as set at the time of the call) to be used. Pass kCFAllocatorNull if no deallocation is desired.

Parameter customBlockSource: If non-NULL, it will be used for the allocation and freeing of the memory block (the blockAllocator parameter is ignored). If provided, and the memoryBlock parameter is NULL, its Allocate() routine must be non-NULL. Allocate will be called once, if successful, when the memoryBlock is allocated. Free() will be called once when the CMBlockBuffer is disposed.

Parameter offsetToData: Offset within the memoryBlock at which the CMBlockBuffer should refer to data.

Parameter dataLength: Number of relevant data bytes, starting at offsetToData, within the memory block.

Parameter flags: Feature and control flags

Parameter blockBufferOut: Receives newly-created CMBlockBuffer object with a retain count of 1. Must not be NULL.

Returns: Returns kCMBlockBufferNoErr if successful.

Safety

• memory_block must be a valid pointer or null.
• custom_block_source must be a valid pointer or null.
• block_buffer_out must be a valid pointer.

pub unsafe fn create_with_buffer_reference( structure_allocator: Option<&CFAllocator>, buffer_reference: &CMBlockBuffer, offset_to_data: usize, data_length: usize, flags: CMBlockBufferFlags, block_buffer_out: NonNull<*mut CMBlockBuffer>, ) -> i32

Creates a new CMBlockBuffer that refers to another CMBlockBuffer.

Creates a new CMBlockBuffer that refers to (a possibly subset portion of) another CMBlockBuffer. The returned CMBlockBuffer may be further expanded using CMBlockBufferAppendMemoryBlock() and/or CMBlockBufferAppendBufferReference().

Parameter structureAllocator: Allocator to use for allocating the CMBlockBuffer object. NULL will cause the default allocator to be used.

Parameter bufferReference: CMBlockBuffer to refer to. This parameter must not be NULL. Unless the kCMBlockBufferPermitEmptyReferenceFlag is passed, it must not be empty and it must have a data length at least large enough to supply the data subset specified (i.e. offsetToData+dataLength bytes).

Parameter offsetToData: Offset within the reference CMBlockBuffer at which the new CMBlockBuffer should refer to data.

Parameter dataLength: Number of relevant data bytes, starting at offsetToData, within the target CMBlockBuffer.

Parameter flags: Feature and control flags

Parameter blockBufferOut: Receives newly-created CMBlockBuffer object with a retain count of 1. Must not be NULL.

Returns: Returns kCMBlockBufferNoErr if successful.

Safety

block_buffer_out must be a valid pointer.

pub unsafe fn create_contiguous( structure_allocator: Option<&CFAllocator>, source_buffer: &CMBlockBuffer, block_allocator: Option<&CFAllocator>, custom_block_source: *const CMBlockBufferCustomBlockSource, offset_to_data: usize, data_length: usize, flags: CMBlockBufferFlags, block_buffer_out: NonNull<*mut CMBlockBuffer>, ) -> i32

Produces a CMBlockBuffer containing a contiguous copy of or reference to the data specified by the parameters.

Produces a CMBlockBuffer containing a contiguous copy of or reference to the data specified by the parameters. The resulting new CMBlockBuffer may contain an allocated copy of the data, or may contain a contiguous CMBlockBuffer reference.

If the kCMBlockBufferAlwaysCopyDataFlag is set in the flags parameter, the resulting CMBlockBuffer will contain an allocated copy of the data rather than a reference to sourceBuffer.

Parameter structureAllocator: Allocator to use for allocating the CMBlockBuffer object. NULL will cause the default allocator to be used.

Parameter sourceBuffer: CMBlockBuffer from which data will be copied or referenced. Must not be NULL nor empty,

Parameter blockAllocator: Allocator to be used for allocating the memoryBlock if a contiguous copy of the data is to be made. Passing NULL will cause the default allocator (as set at the time of the call) to be used.

Parameter customBlockSource: If non-NULL, it will be used for the allocation and freeing of the memory block (the blockAllocator parameter is ignored). If provided, and the memoryBlock parameter is NULL, its Allocate() routine must be non-NULL. Allocate will be called once, if successful, when the memoryBlock is allocated. Free() will be called once when the CMBlockBuffer is disposed.

Parameter offsetToData: Offset within the source CMBlockBuffer at which the new CMBlockBuffer should obtain data.

Parameter dataLength: Number of relevant data bytes, starting at offsetToData, within the source CMBlockBuffer. If zero, the target buffer’s total available dataLength (starting at offsetToData) will be referenced.

Parameter flags: Feature and control flags

Parameter blockBufferOut: Receives newly-created CMBlockBuffer object with a retain count of 1. Must not be NULL.

Returns: Returns kCMBlockBufferNoErr if successful

Safety

• custom_block_source must be a valid pointer or null.
• block_buffer_out must be a valid pointer.

impl CMBlockBuffer

pub unsafe fn append_memory_block( &self, memory_block: *mut c_void, block_length: usize, block_allocator: Option<&CFAllocator>, custom_block_source: *const CMBlockBufferCustomBlockSource, offset_to_data: usize, data_length: usize, flags: CMBlockBufferFlags, ) -> i32

Adds a memoryBlock to an existing CMBlockBuffer.

Adds a memoryBlock to an existing CMBlockBuffer. The memory block may be statically allocated, dynamically allocated using the given allocator or not yet allocated. The CMBlockBuffer’s total data length will be increased by the specified dataLength.

If the kCMBlockBufferAssureMemoryNowFlag is set in the flags parameter, the memory block is allocated immediately using the blockAllocator or customBlockSource. Note that append operations are not thread safe, so care must be taken when appending to BlockBuffers that are used by multiple threads.

Parameter theBuffer: CMBlockBuffer to which the new memoryBlock will be added. Must not be NULL

Parameter memoryBlock: Block of memory to hold buffered data. If NULL, a memory block will be allocated when needed (via a call to CMBlockBufferAssureBlockMemory()) using the provided blockAllocator or customBlockSource. If non-NULL, the block will be used and will be deallocated when the CMBlockBuffer is finalized (i.e. released for the last time).

Parameter blockLength: Overall length of the memory block in bytes. Must not be zero. This is the size of the supplied memory block or the size to allocate if memoryBlock is NULL.

Parameter blockAllocator: Allocator to be used for allocating the memoryBlock, if memoryBlock is NULL. If memoryBlock is non-NULL, this allocator will be used to deallocate it if provided. Passing NULL will cause the default allocator (as set at the time of the call) to be used. Pass kCFAllocatorNull if no deallocation is desired.

Parameter customBlockSource: If non-NULL, it will be used for the allocation and freeing of the memory block (the blockAllocator parameter is ignored). If provided, and the memoryBlock parameter is NULL, its Allocate() routine must be non-NULL. Allocate will be called once, if successful, when the memoryBlock is allocated. Free() will be called once when the CMBlockBuffer is disposed.

Parameter offsetToData: Offset within the memoryBlock at which the CMBlockBuffer should refer to data.

Parameter dataLength: Number of relevant data bytes, starting at offsetToData, within the memory block.

Parameter flags: Feature and control flags

Returns: Returns kCMBlockBufferNoErr if successful.

Safety

• memory_block must be a valid pointer or null.
• custom_block_source must be a valid pointer or null.

pub unsafe fn append_buffer_reference( &self, target_b_buf: &CMBlockBuffer, offset_to_data: usize, data_length: usize, flags: CMBlockBufferFlags, ) -> i32

Adds a CMBlockBuffer reference to an existing CMBlockBuffer.

Adds a buffer reference to (a possibly subset portion of) another CMBlockBuffer to an existing CMBlockBuffer. The CMBlockBuffer’s total data length will be increased by the specified dataLength. Note that append operations are not thread safe, so care must be taken when appending to BlockBuffers that are used by multiple threads.

Parameter theBuffer: CMBlockBuffer to which the new CMBlockBuffer reference will be added. Must not be NULL

Parameter targetBBuf: CMBlockBuffer to refer to. This parameter must not be NULL. Unless the kCMBlockBufferPermitEmptyReferenceFlag is passed, it must not be empty and it must have a data length at least large enough to supply the data subset specified (i.e. offsetToData+dataLength bytes).

Parameter offsetToData: Offset within the target CMBlockBuffer at which the CMBlockBuffer should refer to data.

Parameter dataLength: Number of relevant data bytes, starting at offsetToData, within the target CMBlockBuffer. If zero, the target buffer’s total available dataLength (starting at offsetToData) will be referenced.

Parameter flags: Feature and control flags

Returns: Returns kCMBlockBufferNoErr if successful.

pub unsafe fn assure_block_memory(&self) -> i32

Assures all memory blocks in a CMBlockBuffer are allocated.

Traverses the possibly complex CMBlockBuffer, allocating the memory for any constituent memory blocks that are not yet allocated.

Parameter theBuffer: CMBlockBuffer to operate on. Must not be NULL

Returns: Returns kCMBlockBufferNoErr if successful.

pub unsafe fn access_data_bytes( &self, offset: usize, length: usize, temporary_block: NonNull<c_void>, returned_pointer_out: NonNull<*mut c_char>, ) -> i32

Accesses potentially noncontiguous data in a CMBlockBuffer.

Used for accessing potentially noncontiguous data, this routine will return a pointer directly into the given CMBlockBuffer if possible, otherwise the data will be assembled and copied into the given temporary block and its pointer will be returned.

Parameter theBuffer: CMBlockBuffer to operate on. Must not be NULL

Parameter offset: Offset within the CMBlockBuffer’s offset range.

Parameter length: Desired number of bytes to access at offset

Parameter temporaryBlock: A piece of memory, assumed to be at least length bytes in size. Must not be NULL

Parameter returnedPointerOut: Receives NULL if the desired amount of data could not be accessed at the given offset. Receives non-NULL if it could. The value returned will either be a direct pointer into the CMBlockBuffer or temporaryBlock Must not be NULL.

Returns: Returns kCMBlockBufferNoErr if the desired amount of data could be accessed at the given offset.

Safety

• temporary_block must be a valid pointer.
• returned_pointer_out must be a valid pointer.

pub unsafe fn copy_data_bytes( &self, offset_to_data: usize, data_length: usize, destination: NonNull<c_void>, ) -> i32

Copies bytes from a CMBlockBuffer into a provided memory area.

This function is used to copy bytes out of a CMBlockBuffer into a provided piece of memory. It deals with the possibility of the desired range of data being noncontiguous. The function assumes that the memory at the destination is sufficient to hold the data. If length bytes of data are not available in the CMBlockBuffer, an error is returned and the contents of the destination are undefined.

Parameter theSourceBuffer: The buffer from which data will be copied into the destination

Parameter offsetToData: Offset within the source CMBlockBuffer at which the copy should begin.

Parameter dataLength: Number of bytes to copy, starting at offsetToData, within the source CMBlockBuffer. Must not be zero.

Parameter destination: Memory into which the data should be copied.

Returns: Returns kCMBlockBufferNoErr if the copy succeeded, returns an error otherwise.

Safety

destination must be a valid pointer.

pub unsafe fn replace_data_bytes( source_bytes: NonNull<c_void>, destination_buffer: &CMBlockBuffer, offset_into_destination: usize, data_length: usize, ) -> i32

Copies bytes from a given memory block into a CMBlockBuffer, replacing bytes in the underlying data blocks

This function is used to replace bytes in a CMBlockBuffer’s memory blocks with those from a provided piece of memory. It deals with the possibility of the destination range of data being noncontiguous. CMBlockBufferAssureBlockMemory() is called on the given CMBlockBuffer. If desired range is subsequently not accessible in the CMBlockBuffer, an error is returned and the contents of the CMBlockBuffer are untouched.

Parameter sourceBytes: Memory block from which bytes are copied into the CMBlockBuffer

Parameter destinationBuffer: CMBlockBuffer whose range of bytes will be replaced by the sourceBytes.

Parameter offsetIntoDestination: Offset within the destination CMBlockBuffer at which replacement should begin.

Parameter dataLength: Number of bytes to be replaced, starting at offsetIntoDestination, in the destinationBuffer.

Returns: Returns kCMBlockBufferNoErr if the replacement succeeded, returns an error otherwise.

Safety

source_bytes must be a valid pointer.

pub unsafe fn fill_data_bytes( fill_byte: c_char, destination_buffer: &CMBlockBuffer, offset_into_destination: usize, data_length: usize, ) -> i32

Fills a CMBlockBuffer with a given byte value, replacing bytes in the underlying data blocks

This function is used to fill bytes in a CMBlockBuffer’s memory blocks with a given byte value. It deals with the possibility of the destination range of data being noncontiguous. CMBlockBufferAssureBlockMemory() is called on the given CMBlockBuffer. If desired range is subsequently not accessible in the CMBlockBuffer, an error is returned and the contents of the CMBlockBuffer are untouched.

Parameter fillByte: The value with which to fill the specified data range

Parameter destinationBuffer: CMBlockBuffer whose range of bytes will be filled.

Parameter offsetIntoDestination: Offset within the destination CMBlockBuffer at which filling should begin.

Parameter dataLength: Number of bytes to be filled, starting at offsetIntoDestination, in the destinationBuffer. If zero, the destinationBuffer’s total available dataLength (starting at offsetToData) will be filled.

Returns: Returns kCMBlockBufferNoErr if the fill succeeded, returns an error otherwise.

pub unsafe fn data_pointer( &self, offset: usize, length_at_offset_out: *mut usize, total_length_out: *mut usize, data_pointer_out: *mut *mut c_char, ) -> i32

Gains access to the data represented by a CMBlockBuffer.

Gains access to the data represented by a CMBlockBuffer. A pointer into a memory block is returned which corresponds to the offset within the CMBlockBuffer. The number of bytes addressable at the pointer can also be returned. This length-at-offset may be smaller than the number of bytes actually available starting at the offset if the dataLength of the CMBlockBuffer is covered by multiple memory blocks (a noncontiguous CMBlockBuffer). The data pointer returned will remain valid as long as the original CMBlockBuffer is referenced - once the CMBlockBuffer is released for the last time, any pointers into it will be invalid.

Parameter theBuffer: CMBlockBuffer to operate on. Must not be NULL

Parameter offset: Offset within the buffer’s offset range.

Parameter lengthAtOffsetOut: On return, contains the amount of data available at the specified offset. May be NULL.

Parameter totalLengthOut: On return, contains the block buffer’s total data length (from offset 0). May be NULL. The caller can compare (offset+lengthAtOffset) with totalLength to determine whether the entire CMBlockBuffer has been referenced and whether it is possible to access the CMBlockBuffer’s data with a contiguous reference.

Parameter dataPointerOut: On return, contains a pointer to the data byte at the specified offset; lengthAtOffset bytes are available at this address. May be NULL.

Returns: Returns kCMBlockBufferNoErr if data was accessible at the specified offset within the given CMBlockBuffer, false otherwise.

Safety

• length_at_offset_out must be a valid pointer or null.
• total_length_out must be a valid pointer or null.
• data_pointer_out must be a valid pointer or null.

pub unsafe fn data_length(&self) -> usize

Obtains the total data length reachable via a CMBlockBuffer.

Obtains the total data length reachable via a CMBlockBuffer. This total is the sum of the dataLengths of the CMBlockBuffer’s memoryBlocks and buffer references. Note that the dataLengths are the portions of those constituents that this CMBlockBuffer subscribes to. This CMBlockBuffer presents a contiguous range of offsets from zero to its totalDataLength as returned by this routine.

Parameter theBuffer: CMBlockBuffer to examine.

Returns: Returns the total data length available via this CMBlockBuffer, or zero if it is empty, NULL, or somehow invalid.

pub unsafe fn is_range_contiguous(&self, offset: usize, length: usize) -> bool

Determines whether the specified range within the given CMBlockBuffer is contiguous.

Determines whether the specified range within the given CMBlockBuffer is contiguous. if CMBlockBufferGetDataPointer() were to be called with the same parameters, the returned pointer would address the desired number of bytes.

Parameter theBuffer: CMBlockBuffer to examine. Must not be NULL

Parameter offset: Offset within the buffer’s offset range.

Parameter length: Desired number of bytes to access at offset. If zero, the number of bytes available at offset (dataLength – offset), contiguous or not, is used.

Returns: Returns true if the specified range is contiguous within the CMBlockBuffer, false otherwise. Also returns false if the CMBlockBuffer is NULL or empty.

pub unsafe fn is_empty(&self) -> bool

Indicates whether the given CMBlockBuffer is empty.

Indicates whether the given CMBlockBuffer is empty, i.e., devoid of any memoryBlocks or CMBlockBuffer references. Note that a CMBlockBuffer containing a not-yet allocated memoryBlock is not considered empty.

Parameter theBuffer: CMBlockBuffer to examine. Must not be NULL

Returns: Returns the result of the emptiness test. Will return false if the CMBlockBuffer is NULL.

Methods from Deref<Target = CFType>

pub fn downcast_ref<T>(&self) -> Option<&T>

where T: ConcreteType,

Available on crate feature CMAttachment only.

Attempt to downcast the type to that of type T.

This is the reference-variant. Use CFRetained::downcast if you want to convert a retained type. See also ConcreteType for more details on which types support being converted to.

pub fn retain_count(&self) -> usize

Available on crate feature CMAttachment only.

Get the reference count of the object.

This function may be useful for debugging. You normally do not use this function otherwise.

Beware that some things (like CFNumbers, small CFStrings etc.) may not have a normal retain count for optimization purposes, and can return usize::MAX in that case.

Trait Implementations

impl AsRef<AnyObject> for CMBlockBuffer

fn as_ref(&self) -> &AnyObject

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<CFType> for CMBlockBuffer

fn as_ref(&self) -> &CFType

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<CMBlockBuffer> for CMBlockBuffer

fn as_ref(&self) -> &Self

Converts this type into a shared reference of the (usually inferred) input type.

impl Borrow<AnyObject> for CMBlockBuffer

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value.

impl Borrow<CFType> for CMBlockBuffer

fn borrow(&self) -> &CFType

Immutably borrows from an owned value.

impl ConcreteType for CMBlockBuffer

fn type_id() -> CFTypeID

Obtains the CoreFoundation type ID for the CMBlockBuffer type.

Obtains the CoreFoundation type ID for the CMBlockBuffer type.

Returns: Returns the CFTypeID corresponding to CMBlockBuffer.

impl Debug for CMBlockBuffer

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Deref for CMBlockBuffer

type Target = CFType

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Hash for CMBlockBuffer

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Message for CMBlockBuffer

fn retain(&self) -> Retained<Self>

where Self: Sized,

Increment the reference count of the receiver.

impl PartialEq for CMBlockBuffer

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl RefEncode for CMBlockBuffer

const ENCODING_REF: Encoding

The Objective-C type-encoding for a reference of this type.

impl Type for CMBlockBuffer

fn retain(&self) -> CFRetained<Self>

where Self: Sized,

Increment the reference count of the receiver.

fn as_concrete_TypeRef(&self) -> &Self

👎Deprecated: this is redundant

Helper for easier transition from the core-foundation crate.

unsafe fn wrap_under_get_rule(ptr: *const Self) -> CFRetained<Self>

where Self: Sized,

👎Deprecated: use CFRetained::retain

Helper for easier transition from the core-foundation crate.

fn as_CFTypeRef(&self) -> &CFType

where Self: AsRef<CFType>,

👎Deprecated: this is redundant (CF types deref to CFType)

Helper for easier transition from the core-foundation crate.

unsafe fn wrap_under_create_rule(ptr: *const Self) -> CFRetained<Self>

where Self: Sized,

👎Deprecated: use CFRetained::from_raw

Helper for easier transition from the core-foundation crate.

impl Eq for CMBlockBuffer