Virtual I/O

SndFile2K calls the callbacks provided by the SF_VIRTUAL_IO structure when opening, reading and writing to the virtual file context. More...

Data Structures
struct	SF_VIRTUAL_IO
	Defines virtual file I/O context. More...

Typedefs
typedef sf_count_t(*	sf_vio_get_filelen) (void *user_data)
	Type of user defined function that returns file size. More...
typedef sf_count_t(*	sf_vio_seek) (sf_count_t offset, int whence, void *user_data)
	Type of user defined seek function. More...
typedef sf_count_t(*	sf_vio_read) (void *ptr, sf_count_t count, void *user_data)
	Type of user defined read function. More...
typedef sf_count_t(*	sf_vio_write) (const void *ptr, sf_count_t count, void *user_data)
	Type of user defined write function. More...

Functions
SNDFILE2K_EXPORT SNDFILE *	sf_open_virtual (SF_VIRTUAL_IO *sfvirtual, int mode, SF_INFO *sfinfo, void *user_data)
	Opens sound file using Virtual I/O context. More...
SNDFILE2K_EXPORT SNDFILE *	sf_open_virtual_ex (SF_VIRTUAL_IO *sfvirtual, int mode, SF_INFO *sfinfo, void *user_data)
	Opens sound file using Virtual I/O context. More...

Detailed Description

SndFile2K calls the callbacks provided by the SF_VIRTUAL_IO structure when opening, reading and writing to the virtual file context.

Typedef Documentation

sf_vio_get_filelen

typedef sf_count_t(* sf_vio_get_filelen) (void *user_data)

Type of user defined function that returns file size.

Parameters

[in]

user_data

User defined value.

Returns

Size of file in bytes on success, -1 otherwise.

sf_vio_read

typedef sf_count_t(* sf_vio_read) (void *ptr, sf_count_t count, void *user_data)

Type of user defined read function.

Parameters

[in]	ptr	Pointer to an allocated block memory.
[in]	count	Size in bytes of /c ptr.
[in]	user_data	User defined value.

Returns

Count of bytes actually read or zero otherwise.

sf_vio_seek

typedef sf_count_t(* sf_vio_seek) (sf_count_t offset, int whence, void *user_data)

Type of user defined seek function.

Parameters

[in]	offset	Offset to seek.
[in]	whence	Seek mode, one of SF_SEEK_MODE values.
[in]	user_data	User defined value.

offset must be non-negative if whence is SF_SEEK_SET or SF_SEEK_CUR or non-positive if whence is SF_SEEK_END.

Returns

Non-negative offset from start on the file on success, -1 otherwise.

sf_vio_write

typedef sf_count_t(* sf_vio_write) (const void *ptr, sf_count_t count, void *user_data)

Type of user defined write function.

Parameters

[in]	ptr	Pointer to an allocated block memory.
[in]	count	Size in bytes of ptr.
[in]	user_data	User defined value.

Returns

Count of bytes actually written or zero otherwise.

Function Documentation

sf_open_virtual()

SNDFILE2K_EXPORT SNDFILE* sf_open_virtual	(	SF_VIRTUAL_IO *	sfvirtual,
		int	mode,
		SF_INFO *	sfinfo,
		void *	user_data
	)

Opens sound file using Virtual I/O context.

Parameters

[in]	sfvirtual	Virtual I/O context
[in]	mode	File open mode
[in,out]	sfinfo	Format information
[in]	user_data	User data

sf_open_fd() is similar to sf_open(), but takes Virtual I/O context of already opened file instead of path.

Care should be taken to ensure that the mode of the file represented by the descriptor matches the mode argument.

Returns

A valid pointer to a SNDFILE object on success, NULL otherwise.

Deprecated:

This function is deprecated and will be removed in next major release. Use sf_open_virtual_ex() instead.

See also

sf_open(), sf_wchar_open(), sf_open_fd(), sf_open_virtual_ex()

sf_close()

sf_open_virtual_ex()

SNDFILE2K_EXPORT SNDFILE* sf_open_virtual_ex	(	SF_VIRTUAL_IO *	sfvirtual,
		int	mode,
		SF_INFO *	sfinfo,
		void *	user_data
	)

Opens sound file using Virtual I/O context.

Parameters

[in]	sfvirtual	Virtual I/O context
[in]	mode	File open mode
[in,out]	sfinfo	Format information
[in]	user_data	User data

sf_open_virtual_ex() is similar to sf_open(), but takes Virtual I/O context of already opened file instead of path.

sf_open_virtual_ex() uses new SF_VIRTUAL_IO members: SF_VIRTUAL_IO::flush, SF_VIRTUAL_IO::set_filelen, SF_VIRTUAL_IO::is_pipe, SF_VIRTUAL_IO::ref and SF_VIRTUAL_IO::unref. Anyway, all this callbaks are not required and could be set to NULL.

• SF_VIRTUAL_IO::flush is helpful in write mode, performing flashing cache data to disk.
• SF_VIRTUAL_IO::set_filelen truncates file to desired size by the library.
• SF_VIRTUAL_IO::is_pipe indicates that stream is pipe, activating internal pipe support.
• SF_VIRTUAL_IO::ref and SF_VIRTUAL_IO::unref could be implemented to control stream life time. When these members are implemented, library will call ref when file is opened, and call unref before closing file. You can pass as user_data pointer to struct with some counter member, your implementation of ref must increase this value, and must decrease it and when it reaches zero close stream and free resources. Now, when initial value is zero, library will call and set counter to 1, holding reference. In sf_close() unref will be called, setting counter to 0 and calls yours cleanup code.

Care should be taken to ensure that the mode of the file represented by the descriptor matches the mode argument.

Returns

A valid pointer to a SNDFILE object on success, NULL otherwise.

See also

sf_open(), sf_wchar_open(), sf_open_fd(), sf_open_virtual()

sf_close()