Instance.hpp 11.5 KB
Newer Older
Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
1
/*****************************************************************************
2
 * Instance.hpp: Instance API
Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
3
 *****************************************************************************
4
 * Copyright © 2015 libvlcpp authors & VideoLAN
Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
5
 *
6
 * Authors: Alexey Sokolov <alexey+vlc@asokolov.org>
7
 *          Hugo Beauzée-Luyssen <hugo@beauzee.fr>
Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation; either version 2.1 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
 *****************************************************************************/

#ifndef LIBVLC_CXX_INSTANCE_H
#define LIBVLC_CXX_INSTANCE_H

27
#include "common.hpp"
28
#include "Internal.hpp"
29
#include "structures.hpp"
Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
30

31 32 33
#include <string>
#include <vector>

34 35
namespace VLC
{
Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
36

37
class Instance : public Internal<libvlc_instance_t>, private EventOwner<2>
Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
38
{
39 40 41 42 43 44
private:
    enum class EventIdx : unsigned int
    {
        Exit,
        Log
    };
Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67
public:
    /**
     * Create and initialize a libvlc instance. This functions accept a list
     * of "command line" arguments similar to the main(). These arguments
     * affect the LibVLC instance default configuration.
     *
     * \version Arguments are meant to be passed from the command line to
     * LibVLC, just like VLC media player does. The list of valid arguments
     * depends on the LibVLC version, the operating system and platform, and
     * set of available LibVLC plugins. Invalid or unsupported arguments will
     * cause the function to fail (i.e. return NULL). Also, some arguments
     * may alter the behaviour or otherwise interfere with other LibVLC
     * functions.
     *
     * \warning There is absolutely no warranty or promise of forward,
     * backward and cross-platform compatibility with regards to
     * Instance::Instance() arguments. We recommend that you do not use them,
     * other than when debugging.
     *
     * \param argc  the number of arguments (should be 0)
     *
     * \param argv  list of arguments (should be NULL)
     */
68 69 70 71
    Instance(int argc, const char *const * argv)
        : Internal{ libvlc_new( argc, argv ), libvlc_release }
    {
    }
72

73 74 75 76 77 78 79
    /**
     * Create an empty VLC instance.
     *
     * Calling any method on such an instance is undefined.
    */
    Instance() = default;

80 81 82 83 84
    /**
     * Check if 2 Instance objects contain the same libvlc_instance_t.
     * \param another another Instance
     * \return true if they contain the same libvlc_instance_t
     */
85 86 87 88 89
    bool operator==(const Instance& another) const
    {
        return m_obj == another.m_obj;
    }

90

Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
91 92 93 94 95 96 97
    /**
     * Try to start a user interface for the libvlc instance.
     *
     * \param name  interface name, or NULL for default
     *
     * \return 0 on success, -1 on error.
     */
98 99
    int addIntf(const std::string& name)
    {
100
        return libvlc_add_intf( *this, name.c_str() );
101
    }
Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121

    /**
     * Registers a callback for the LibVLC exit event. This is mostly useful
     * if the VLC playlist and/or at least one interface are started with
     * libvlc_playlist_play() or Instance::addIntf() respectively. Typically,
     * this function will wake up your application main loop (from another
     * thread).
     *
     * \note This function should be called before the playlist or interface
     * are started. Otherwise, there is a small race condition: the exit
     * event could be raised before the handler is registered.
     *
     * \param cb  callback to invoke when LibVLC wants to exit, or NULL to
     * disable the exit handler (as by default)
     *
     * \param opaque  data pointer for the callback
     *
     * \warning This function and Instance::wait() cannot be used at the same
     * time.
     */
122 123
    template <typename ExitCb>
    void setExitHandler(ExitCb&& exitCb)
124
    {
125 126 127 128
        static_assert(signature_match_or_nullptr<ExitCb, void()>::value, "Mismatched exit callback" );
        libvlc_set_exit_handler( *this,
            CallbackWrapper<(int)EventIdx::Exit, void(*)(void*)>::wrap( this, std::forward<ExitCb>( exitCb ) ),
            static_cast<EventOwner<2>*>( this ) );
129
    }
Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
130 131 132 133 134 135 136 137 138 139 140 141

    /**
     * Sets the application name. LibVLC passes this as the user agent string
     * when a protocol requires it.
     *
     * \param name  human-readable application name, e.g. "FooBar player
     * 1.2.3"
     *
     * \param http  HTTP User Agent, e.g. "FooBar/1.2.3 Python/2.6.0"
     *
     * \version LibVLC 1.1.1 or later
     */
142 143
    void setUserAgent(const std::string& name, const std::string& http)
    {
144
        libvlc_set_user_agent( *this, name.c_str(), http.c_str() );
145
    }
Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
146 147 148 149 150 151 152 153 154 155 156 157 158

    /**
     * Sets some meta-information about the application. See also
     * Instance::setUserAgent() .
     *
     * \param id  Java-style application identifier, e.g. "com.acme.foobar"
     *
     * \param version  application version numbers, e.g. "1.2.3"
     *
     * \param icon  application icon name, e.g. "foobar"
     *
     * \version LibVLC 2.1.0 or later.
     */
159 160
    void setAppId(const std::string& id, const std::string& version, const std::string& icon)
    {
161
        libvlc_set_app_id( *this, id.c_str(), version.c_str(), icon.c_str() );
162
    }
Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
163 164 165 166 167 168 169 170 171 172

    /**
     * Unsets the logging callback for a LibVLC instance. This is rarely
     * needed: the callback is implicitly unset when the instance is
     * destroyed. This function will wait for any pending callbacks
     * invocation to complete (causing a deadlock if called from within the
     * callback).
     *
     * \version LibVLC 2.1.0 or later
     */
173 174
    void logUnset()
    {
175
        libvlc_log_unset( *this );
176
    }
Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193

    /**
     * Sets the logging callback for a LibVLC instance. This function is
     * thread-safe: it will wait for any pending callbacks invocation to
     * complete.
     *
     * \note Some log messages (especially debug) are emitted by LibVLC while
     * is being initialized. These messages cannot be captured with this
     * interface.
     *
     * \warning A deadlock may occur if this function is called from the
     * callback.
     *
     * \param p_instance  libvlc instance
     *
     * \version LibVLC 2.1.0 or later
     */
194 195
    template <typename LogCb>
    void logSet(LogCb&& logCb)
196
    {
197 198 199 200 201 202 203 204 205 206
        static_assert(signature_match<LogCb, void(int, const libvlc_log_t*, std::string)>::value,
                      "Mismatched log callback" );
        auto wrapper = [logCb](int level, const libvlc_log_t* ctx, const char* format, va_list va) {
            char *message;
            vasprintf( &message, format, va);
            std::unique_ptr<char, void(*)(void*)> mPtr{ message, free };
            logCb( level, ctx, std::string{ message } );
        };
        libvlc_log_set( *this, CallbackWrapper<(int)EventIdx::Log, libvlc_log_cb>::wrap( this, std::move( wrapper ) ),
                        static_cast<EventOwner<2>*>( this ) );
207
    }
Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
208 209 210 211 212 213 214 215 216

    /**
     * Sets up logging to a file.
     *
     * \param stream  FILE pointer opened for writing (the FILE pointer must
     * remain valid until Instance::logUnset() )
     *
     * \version LibVLC 2.1.0 or later
     */
217 218
    void logSetFile(FILE * stream)
    {
219
        libvlc_log_set_file( *this, stream );
220
    }
Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
221 222 223 224 225 226 227 228 229 230 231 232

    /**
     * Returns a list of audio filters that are available.
     *
     * \return a list of module descriptions. It should be freed with
     * ModuleDescription::moduleDescriptionListRelease() . In case of an
     * error, NULL is returned.
     *
     * \see ModuleDescription
     *
     * \see ModuleDescription::moduleDescriptionListRelease()
     */
233 234
    std::vector<ModuleDescription> audioFilterList()
    {
235 236 237 238 239
        auto releaser = [](libvlc_module_description_t* ptr) { libvlc_module_description_list_release(ptr); };
        auto ptr = std::unique_ptr<libvlc_module_description_t, decltype(releaser)>( libvlc_audio_filter_list_get(*this), releaser );
        if ( ptr == nullptr )
            return {};
        libvlc_module_description_t* p = ptr.get();
240 241 242
        std::vector<ModuleDescription> res;
        while ( p != NULL )
        {
243
            res.emplace_back( p );
244 245 246 247 248
            p = p->p_next;
        }
        return res;
    }

Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
249 250 251 252 253 254 255 256 257 258 259 260

    /**
     * Returns a list of video filters that are available.
     *
     * \return a list of module descriptions. It should be freed with
     * ModuleDescription::moduleDescriptionListRelease() . In case of an
     * error, NULL is returned.
     *
     * \see ModuleDescription
     *
     * \see ModuleDescription::moduleDescriptionListRelease()
     */
261 262
    std::vector<ModuleDescription> videoFilterList()
    {
263 264 265 266 267
        auto releaser = [](libvlc_module_description_t* ptr) { libvlc_module_description_list_release(ptr); };
        auto ptr = std::unique_ptr<libvlc_module_description_t, decltype(releaser)>( libvlc_video_filter_list_get(*this), releaser );
        if ( ptr == nullptr )
            return {};
        libvlc_module_description_t* p = ptr.get();
268 269 270
        std::vector<ModuleDescription> res;
        while ( p != NULL )
        {
271
            res.emplace_back( p );
272 273 274 275
            p = p->p_next;
        }
        return res;
    }
Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
276 277 278 279 280 281 282 283 284 285

    /**
     * Gets the list of available audio output modules.
     *
     * \return list of available audio outputs. It must be freed it with
     *
     * \see AudioOutputDescription::audioOutputListRelease()
     *
     * \see AudioOutputDescription . In case of error, NULL is returned.
     */
286 287
    std::vector<AudioOutputDescription> audioOutputList()
    {
288
        libvlc_audio_output_t* result = libvlc_audio_output_list_get(*this);
289 290 291 292 293 294
        std::vector<AudioOutputDescription> res;
        if ( result == NULL )
            return res;
        libvlc_audio_output_t* p = result;
        while ( p != NULL )
        {
295
            res.emplace_back( p );
296 297 298 299 300
            p = p->p_next;
        }
        libvlc_audio_output_list_release(result);
        return res;
    }
Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319

    /**
     * Gets a list of audio output devices for a given audio output module,
     *
     * \see Audio::outputDeviceSet() .
     *
     * \note Not all audio outputs support this. In particular, an empty
     * (NULL) list of devices does imply that the specified audio output does
     * not work.
     *
     * \note The list might not be exhaustive.
     *
     * \warning Some audio output devices in the list might not actually work
     * in some circumstances. By default, it is recommended to not specify
     * any explicit audio device.
     *
     * \param psz_aout  audio output name (as returned by
     * Instance::audioOutputList() )
     *
320
     * \return A vector containing all audio output devices for this module
Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
321 322 323
     *
     * \version LibVLC 2.1.0 or later.
     */
324 325
    std::vector<AudioOutputDeviceDescription> audioOutputDeviceList(const std::string& aout)
    {
326
        libvlc_audio_output_device_t* devices = libvlc_audio_output_device_list_get( *this, aout.c_str() );
327 328 329 330
        std::vector<AudioOutputDeviceDescription> res;
        if ( devices == NULL )
            return res;
        for ( libvlc_audio_output_device_t* p = devices; p != NULL; p = p->p_next )
331
            res.emplace_back( p );
332 333 334 335
        libvlc_audio_output_device_list_release( devices );
        return res;
    }

Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
336 337 338 339 340 341
};

} // namespace VLC

#endif