Chunks API

Getting and setting of chunks from within a sound file. More...

Data Structures
struct	SF_CHUNK_INFO
	Describes sound file chunk. More...

Typedefs
typedef struct SF_CHUNK_ITERATOR	SF_CHUNK_ITERATOR
	An opaque structure to an iterator over the all chunks of a given id.

Functions
SNDFILE2K_EXPORT int	sf_set_chunk (SNDFILE *sndfile, const SF_CHUNK_INFO *chunk_info)
	Sets the specified chunk info. More...
SNDFILE2K_EXPORT SF_CHUNK_ITERATOR *	sf_get_chunk_iterator (SNDFILE *sndfile, const SF_CHUNK_INFO *chunk_info)
	Gets an iterator for all chunks matching chunk_info. More...
SNDFILE2K_EXPORT SF_CHUNK_ITERATOR *	sf_next_chunk_iterator (SF_CHUNK_ITERATOR *iterator)
	Iterates through chunks by incrementing the iterator. More...
SNDFILE2K_EXPORT int	sf_get_chunk_size (const SF_CHUNK_ITERATOR *it, SF_CHUNK_INFO *chunk_info)
	Gets the size of the specified chunk. More...
SNDFILE2K_EXPORT int	sf_get_chunk_data (const SF_CHUNK_ITERATOR *it, SF_CHUNK_INFO *chunk_info)
	Gets the specified chunk data. More...

Detailed Description

Getting and setting of chunks from within a sound file.

These functions allow the getting and setting of chunks within a sound file (for those formats which allow it).

These functions fail safely. Specifically, they will not allow you to overwrite existing chunks or add extra versions of format specific reserved chunks but should allow you to retrieve any and all chunks (may not be implemented for all chunks or all file formats).

Function Documentation

sf_get_chunk_data()

SNDFILE2K_EXPORT int sf_get_chunk_data	(	const SF_CHUNK_ITERATOR *	it,
		SF_CHUNK_INFO *	chunk_info
	)

Gets the specified chunk data.

Parameters

[in]	it	Chunk iterafor
[out]	chunk_info	Pointer to a SF_CHUNK_INFO struct

If the specified chunk exists, up to chunk_info->datalen bytes of the chunk data will be copied into the chunk_info->data buffer (allocated by the caller) and the chunk_info->datalen field updated to reflect the size of the data. The id and id_size field will be updated according to the retrieved chunk.

If the chunk doesn't exist chunk_info->datalen will be zero, and the id and id_size fields will be undefined.

Returns

SF_ERR_NO_ERROR on success, negative error code otherwise.

sf_get_chunk_iterator()

SNDFILE2K_EXPORT SF_CHUNK_ITERATOR* sf_get_chunk_iterator	(	SNDFILE *	sndfile,
		const SF_CHUNK_INFO *	chunk_info
	)

Gets an iterator for all chunks matching chunk_info.

Parameters

[in]	sndfile	Pointer to a sound file state
[in]	chunk_info	Pointer to a SF_CHUNK_INFO struct

The iterator will point to the first chunk matching chunk_info.

Chunks are matching, if (chunk_info->id) matches the first (chunk_info->id_size) bytes of a chunk found in the SNDFILE* handle.

If chunk_info is NULL, an iterator to all chunks in the SNDFILE* handle is returned.

The values of chunk_info->datalen and chunk_info->data are ignored.

If no matching chunks are found in the sndfile, NULL is returned.

The returned iterator will stay valid until one of the following occurs:

1. The sndfile is closed.
2. A new chunk is added using sf_set_chunk().
3. Another chunk iterator function is called on the same SNDFILE* handle that causes the iterator to be modified.

The memory for the iterator belongs to the SNDFILE* handle and is freed when sf_close() is called.

Returns

Chunk iterator on success, NULL otherwise.

sf_get_chunk_size()

SNDFILE2K_EXPORT int sf_get_chunk_size	(	const SF_CHUNK_ITERATOR *	it,
		SF_CHUNK_INFO *	chunk_info
	)

Gets the size of the specified chunk.

Parameters

[in]	it	Chunk iterafor
[out]	chunk_info	Pointer to a SF_CHUNK_INFO struct

If the specified chunk exists, the size will be returned in the SF_CHUNK_INFO::datalen field of the SF_CHUNK_INFO struct.

Additionally, the id of the chunk will be copied to the id field of the SF_CHUNK_INFO struct and it's id_size field will be updated accordingly.

If the chunk doesn't exist chunk_info->datalen will be zero, and the id and id_size fields will be undefined.

Returns

SF_ERR_NO_ERROR on success, negative error code otherwise.

sf_next_chunk_iterator()

SNDFILE2K_EXPORT SF_CHUNK_ITERATOR* sf_next_chunk_iterator

(

SF_CHUNK_ITERATOR *

iterator

)

Iterates through chunks by incrementing the iterator.

Parameters

[in]

iterator

Current chunk iterator

Increments the iterator and returns a handle to the new one.

After this call, iterator will no longer be valid, and you must use the newly returned handle from now on.

The returned handle can be used to access the next chunk matching the criteria as defined in sf_get_chunk_iterator().

If iterator points to the last chunk, this will free all resources associated with iterator and return NULL.

The returned iterator will stay valid until sf_get_chunk_iterator_next is called again, the sndfile is closed or a new chunk us added.

Returns

Next chunk interator on success, NULL otherwise.

sf_set_chunk()

SNDFILE2K_EXPORT int sf_set_chunk	(	SNDFILE *	sndfile,
		const SF_CHUNK_INFO *	chunk_info
	)

Sets the specified chunk info.

Parameters

[in]	sndfile	Pointer to a sound file state
[in]	chunk_info	Pointer to a SF_CHUNK_INFO struct

Chunk info must be done before any audio data is written to the file.

This will fail for format specific reserved chunks.

The chunk_info->data pointer must be valid until the file is closed.

Returns

Returns SF_ERR_NO_ERROR on success or non-zero on failure.