Something went wrong. Try again.
🎥 Command line media player
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224/* Copyright (C) 2017 the mpv developers * * Permission to use, copy, modify, and/or distribute this software for any * purpose with or without fee is hereby granted, provided that the above * copyright notice and this permission notice appear in all copies. * * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */
#ifndef MPV_CLIENT_API_STREAM_CB_H_#define MPV_CLIENT_API_STREAM_CB_H_
#include "client.h"
#ifdef __cplusplusextern "C" {#endif
/** * Warning: this API is not stable yet. * * Overview * -------- * * This API can be used to make mpv read from a stream with a custom * implementation. This interface is inspired by funopen on BSD and * fopencookie on linux. The stream is backed by user-defined callbacks * which can implement customized open, read, seek, size and close behaviors. * * Usage * ----- * * Register your stream callbacks with the mpv_stream_cb_add_ro() function. You * have to provide a mpv_stream_cb_open_ro_fn callback to it (open_fn argument). * * Once registered, you can `loadfile myprotocol://myfile`. Your open_fn will be * invoked with the URI and you must fill out the provided mpv_stream_cb_info * struct. This includes your stream callbacks (like read_fn), and an opaque * cookie, which will be passed as the first argument to all the remaining * stream callbacks. * * Note that your custom callbacks must not invoke libmpv APIs as that would * cause a deadlock. (Unless you call a different mpv_handle than the one the * callback was registered for, and the mpv_handles refer to different mpv * instances.) * * Stream lifetime * --------------- * * A stream remains valid until its close callback has been called. It's up to * libmpv to call the close callback, and the libmpv user cannot close it * directly with the stream_cb API. * * For example, if you consider your custom stream to become suddenly invalid * (maybe because the underlying stream died), libmpv will continue using your * stream. All you can do is returning errors from each callback, until libmpv * gives up and closes it. * * Protocol registration and lifetime * ---------------------------------- * * Protocols remain registered until the mpv instance is terminated. This means * in particular that it can outlive the mpv_handle that was used to register * it, but once mpv_terminate_destroy() is called, your registered callbacks * will not be called again. * * Protocol unregistration is finished after the mpv core has been destroyed * (e.g. after mpv_terminate_destroy() has returned). * * If you do not call mpv_terminate_destroy() yourself (e.g. plugin-style code), * you will have to deal with the registration or even streams outliving your * code. Here are some possible ways to do this: * - call mpv_terminate_destroy(), which destroys the core, and will make sure * all streams are closed once this function returns * - you refcount all resources your stream "cookies" reference, so that it * doesn't matter if streams live longer than expected * - create "cancellation" semantics: after your protocol has been unregistered, * notify all your streams that are still opened, and make them drop all * referenced resources - then return errors from the stream callbacks as * long as the stream is still opened * */
/** * Read callback used to implement a custom stream. The semantics of the * callback match read(2) in blocking mode. Short reads are allowed (you can * return less bytes than requested, and libmpv will retry reading the rest * with a nother call). If no data can be immediately read, the callback must * block until there is new data. A return of 0 will be interpreted as final * EOF, although libmpv might retry the read, or seek to a different position. * * @param cookie opaque cookie identifying the stream, * returned from mpv_stream_cb_open_fn * @param buf buffer to read data into * @param size of the buffer * @return number of bytes read into the buffer * @return 0 on EOF * @return -1 on error */typedef int64_t (*mpv_stream_cb_read_fn)(void *cookie, char *buf, uint64_t nbytes);
/** * Seek callback used to implement a custom stream. * * Note that mpv will issue a seek to position 0 immediately after opening. This * is used to test whether the stream is seekable (since seekability might * depend on the URI contents, not just the protocol). Return * MPV_ERROR_UNSUPPORTED if seeking is not implemented for this stream. This * seek also servies to establish the fact that streams start at position 0. * * This callback can be NULL, in which it behaves as if always returning * MPV_ERROR_UNSUPPORTED. * * @param cookie opaque cookie identifying the stream, * returned from mpv_stream_cb_open_fn * @param offset target absolut stream position * @return the resulting offset of the stream * MPV_ERROR_UNSUPPORTED or MPV_ERROR_GENERIC if the seek failed */typedef int64_t (*mpv_stream_cb_seek_fn)(void *cookie, int64_t offset);
/** * Size callback used to implement a custom stream. * * Return MPV_ERROR_UNSUPPORTED if no size is known. * * This callback can be NULL, in which it behaves as if always returning * MPV_ERROR_UNSUPPORTED. * * @param cookie opaque cookie identifying the stream, * returned from mpv_stream_cb_open_fn * @return the total size in bytes of the stream */typedef int64_t (*mpv_stream_cb_size_fn)(void *cookie);
/** * Close callback used to implement a custom stream. * * @param cookie opaque cookie identifying the stream, * returned from mpv_stream_cb_open_fn */typedef void (*mpv_stream_cb_close_fn)(void *cookie);
/** * See mpv_stream_cb_open_ro_fn callback. */typedef struct mpv_stream_cb_info { /** * Opaque user-provided value, which will be passed to the other callbacks. * The close callback will be called to release the cookie. It is not * interpreted by mpv. It doesn't even need to be a valid pointer. * * The user sets this in the mpv_stream_cb_open_ro_fn callback. */ void *cookie;
/** * Callbacks set by the user in the mpv_stream_cb_open_ro_fn callback. Some * of them are optional, and can be left unset. * * The following callbacks are mandatory: read_fn, close_fn */ mpv_stream_cb_read_fn read_fn; mpv_stream_cb_seek_fn seek_fn; mpv_stream_cb_size_fn size_fn; mpv_stream_cb_close_fn close_fn;} mpv_stream_cb_info;
/** * Open callback used to implement a custom read-only (ro) stream. The user * must set the callback fields in the passed info struct. The cookie field * also can be set to store state associated to the stream instance. * * Note that the info struct is valid only for the duration of this callback. * You can't change the callbacks or the pointer to the cookie at a later point. * * Each stream instance created by the open callback can have different * callbacks. * * The close_fn callback will terminate the stream instance. The pointers to * your callbacks and cookie will be discarded, and the callbacks will not be * called again. * * @param user_data opaque user data provided via mpv_stream_cb_add() * @param uri name of the stream to be opened (with protocol prefix) * @param info fields which the user should fill * @return 0 on success, MPV_ERROR_LOADING_FAILED if the URI cannot be opened. */typedef int (*mpv_stream_cb_open_ro_fn)(void *user_data, char *uri, mpv_stream_cb_info *info);
/** * Add a custom stream protocol. This will register a protocol handler under * the given protocol prefix, and invoke the given callbacks if an URI with the * matching protocol prefix is opened. * * The "ro" is for read-only - only read-only streams can be registered with * this function. * * The callback remains registered until the mpv core is registered. * * If a custom stream with the same name is already registered, then the * MPV_ERROR_INVALID_PARAMETER error is returned. * * @param protocol protocol prefix, for example "foo" for "foo://" URIs * @param user_data opaque pointer passed into the mpv_stream_cb_open_fn * callback. * @return error code */int mpv_stream_cb_add_ro(mpv_handle *ctx, const char *protocol, void *user_data, mpv_stream_cb_open_ro_fn open_fn);
#ifdef __cplusplus}#endif
#endif