mpg123 low level I/O

Functions
MPG123_EXPORT int	mpg123_replace_buffer (mpg123_handle *mh, void *data, size_t size)
MPG123_EXPORT size_t	mpg123_outblock (mpg123_handle *mh)
MPG123_EXPORT int	mpg123_replace_reader (mpg123_handle *mh, ssize_t(*r_read)(int, void *, size_t), off_t(*r_lseek)(int, off_t, int))
MPG123_EXPORT int	mpg123_replace_reader_handle (mpg123_handle *mh, ssize_t(*r_read)(void *, void *, size_t), off_t(*r_lseek)(void *, off_t, int), void(*cleanup)(void *))

Detailed Description

You may want to do tricky stuff with I/O that does not work with mpg123's default file access or you want to make it decode into your own pocket...

Function Documentation

mpg123_outblock()

MPG123_EXPORT size_t mpg123_outblock

(

mpg123_handle *

mh

)

The max size of one frame's decoded output with current settings. Use that to determine an appropriate minimum buffer size for decoding one frame.

Parameters

mh

handle

Returns

maximum decoded data size in bytes

Definition at line 653 of file libmpg123.c.

{
    /* Try to be helpful and never return zero output block size. */
    if(mh != NULL && mh->outblock > 0) return mh->outblock;
    else return mpg123_safe_buffer();
}

mpg123_replace_buffer()

MPG123_EXPORT int mpg123_replace_buffer	(	mpg123_handle *	mh,
		void *	data,
		size_t	size
	)

Replace default internal buffer with user-supplied buffer. Instead of working on it's own private buffer, mpg123 will directly use the one you provide for storing decoded audio. Note that the required buffer size could be bigger than expected from output encoding if libmpg123 has to convert from primary decoder output (p.ex. 32 bit storage for 24 bit output).

Note: The type of data changed to a void pointer in mpg123 1.26.0 (API version 45).

Parameters

mh	handle
data	pointer to user buffer
size	of buffer in bytes

Returns

MPG123_OK on success

Definition at line 219 of file frame.c.

{
    debug2("replace buffer with %p size %"SIZE_P, data, (size_p)size);
    if(mh == NULL) return MPG123_BAD_HANDLE;
    /* Will accept any size, the error comes later... */
    if(data == NULL)
    {
        mh->err = MPG123_BAD_BUFFER;
        return MPG123_ERR;
    }
    if(mh->buffer.rdata != NULL) free(mh->buffer.rdata);
    mh->own_buffer = FALSE;
    mh->buffer.rdata = NULL;
    mh->buffer.data = data;
    mh->buffer.size = size;
    mh->buffer.fill = 0;
    return MPG123_OK;
}

mpg123_replace_reader()

MPG123_EXPORT int mpg123_replace_reader	(	mpg123_handle *	mh,
		ssize_t(*)(int, void *, size_t)	r_read,
		off_t(*)(int, off_t, int)	r_lseek
	)

Replace low-level stream access functions; read and lseek as known in POSIX. You can use this to make any fancy file opening/closing yourself, using mpg123_open_fd() to set the file descriptor for your read/lseek (doesn't need to be a "real" file descriptor...). Setting a function to NULL means that the default internal read is used (active from next mpg123_open call on). Note: As it would be troublesome to mess with this while having a file open, this implies mpg123_close().

Parameters

mh	handle
r_read	callback for reading (behaviour like POSIX read)
r_lseek	callback for seeking (like POSIX lseek)

Returns

MPG123_OK on success

Definition at line 601 of file lfs_wrap.c.

{
    struct wrap_data* ioh;

    if(mh == NULL) return MPG123_ERR;

    mpg123_close(mh);
    ioh = wrap_get(mh);
    if(ioh == NULL) return MPG123_ERR;

    /* If both callbacks are NULL, switch totally to internal I/O, else just use fallback for at most half of them. */
    if(r_read == NULL && r_lseek == NULL)
    {
        /* Only the type is actually important to disable the code. */
        ioh->iotype = 0;
        ioh->fd = -1;
        ioh->r_read = NULL;
        ioh->r_lseek = NULL;
    }
    else
    {
        ioh->iotype = IO_FD;
        ioh->fd = -1; /* On next mpg123_open_fd(), this gets a value. */
        ioh->r_read = r_read != NULL ? r_read : fallback_read;
        ioh->r_lseek = r_lseek != NULL ? r_lseek : fallback_lseek;
    }

    /* The real reader replacement will happen while opening. */
    return MPG123_OK;
}

mpg123_replace_reader_handle()

MPG123_EXPORT int mpg123_replace_reader_handle	(	mpg123_handle *	mh,
		ssize_t(*)(void *, void *, size_t)	r_read,
		off_t(*)(void *, off_t, int)	r_lseek,
		void(*)(void *)	cleanup
	)

Replace I/O functions with your own ones operating on some kind of handle instead of integer descriptors. The handle is a void pointer, so you can pass any data you want... mpg123_open_handle() is the call you make to use the I/O defined here. There is no fallback to internal read/seek here. Note: As it would be troublesome to mess with this while having a file open, this mpg123_close() is implied here.

Parameters

mh	handle
r_read	callback for reading (behaviour like POSIX read)
r_lseek	callback for seeking (like POSIX lseek)
cleanup	A callback to clean up an I/O handle on mpg123_close, can be NULL for none (you take care of cleaning your handles).

Returns

MPG123_OK on success

Definition at line 632 of file lfs_wrap.c.

{
    struct wrap_data* ioh;

    if(mh == NULL) return MPG123_ERR;

    mpg123_close(mh);
    ioh = wrap_get(mh);
    if(ioh == NULL) return MPG123_ERR;

    ioh->iotype = IO_HANDLE;
    ioh->handle = NULL;
    ioh->r_h_read = r_read;
    ioh->r_h_lseek = r_lseek;
    ioh->h_cleanup = cleanup;

    /* The real reader replacement will happen while opening. */
    return MPG123_OK;
}

Referenced by mpg123_open(), mpg123_open_fd(), and mpg123_open_handle().