diff options
Diffstat (limited to 'chromium/ppapi/cpp/media_stream_audio_track.h')
-rw-r--r-- | chromium/ppapi/cpp/media_stream_audio_track.h | 144 |
1 files changed, 144 insertions, 0 deletions
diff --git a/chromium/ppapi/cpp/media_stream_audio_track.h b/chromium/ppapi/cpp/media_stream_audio_track.h new file mode 100644 index 00000000000..680e52b832e --- /dev/null +++ b/chromium/ppapi/cpp/media_stream_audio_track.h @@ -0,0 +1,144 @@ +// Copyright 2014 The Chromium Authors. All rights reserved. +// Use of this source code is governed by a BSD-style license that can be +// found in the LICENSE file. + +#ifndef PPAPI_CPP_MEDIA_STREAM_AUDIO_TRACK_H_ +#define PPAPI_CPP_MEDIA_STREAM_AUDIO_TRACK_H_ + +#include <string> + +#include "ppapi/c/ppb_media_stream_audio_track.h" +#include "ppapi/cpp/resource.h" +#include "ppapi/cpp/var.h" + +/// @file +/// This file defines the <code>MediaStreamAudioTrack</code> interface for an +/// audio source resource, which receives audio buffers from a MediaStream audio +/// track in the browser. + +namespace pp { + +class AudioBuffer; +class CompletionCallback; +template <typename T> class CompletionCallbackWithOutput; + +/// The <code>MediaStreamAudioTrack</code> class contains methods for +/// receiving audio buffers from a MediaStream audio track in the browser. +class MediaStreamAudioTrack : public Resource { + public: + /// Default constructor for creating an is_null() + /// <code>MediaStreamAudioTrack</code> object. + MediaStreamAudioTrack(); + + /// The copy constructor for <code>MediaStreamAudioTrack</code>. + /// + /// @param[in] other A reference to a <code>MediaStreamAudioTrack</code>. + MediaStreamAudioTrack(const MediaStreamAudioTrack& other); + + /// Constructs a <code>MediaStreamAudioTrack</code> from + /// a <code>Resource</code>. + /// + /// @param[in] resource A <code>PPB_MediaStreamAudioTrack</code> resource. + explicit MediaStreamAudioTrack(const Resource& resource); + + /// A constructor used when you have received a <code>PP_Resource</code> as a + /// return value that has had 1 ref added for you. + /// + /// @param[in] resource A <code>PPB_MediaStreamAudioTrack</code> resource. + MediaStreamAudioTrack(PassRef, PP_Resource resource); + + ~MediaStreamAudioTrack(); + + /// Configures underlying buffer buffers for incoming audio samples. + /// If the application doesn't want to drop samples, then the + /// <code>PP_MEDIASTREAMAUDIOTRACK_ATTRIB_BUFFERS</code> should be + /// chosen such that inter-buffer processing time variability won't overrun + /// all input buffers. If all buffers are filled, then samples will be + /// dropped. The application can detect this by examining the timestamp on + /// returned buffers. If <code>Configure()</code> is not called, default + /// settings will be used. Calls to Configure while the plugin holds + /// buffers will fail. + /// Example usage from plugin code: + /// @code + /// int32_t attribs[] = { + /// PP_MEDIASTREAMAUDIOTRACK_ATTRIB_BUFFERS, 4, + /// PP_MEDIASTREAMAUDIOTRACK_ATTRIB_DURATION, 10, + /// PP_MEDIASTREAMAUDIOTRACK_ATTRIB_NONE}; + /// track.Configure(attribs, callback); + /// @endcode + /// + /// @param[in] attrib_list A list of attribute name-value pairs in which each + /// attribute is immediately followed by the corresponding desired value. + /// The list is terminated by + /// <code>PP_MEDIASTREAMAUDIOTRACK_AUDIO_NONE</code>. + /// @param[in] callback A <code>CompletionCallback</code> to be called upon + /// completion of <code>Configure()</code>. + /// + /// @return An int32_t containing a result code from <code>pp_errors.h</code>. + int32_t Configure(const int32_t attributes[], + const CompletionCallback& callback); + + /// Gets attribute value for a given attribute name. + /// + /// @param[in] attrib A <code>PP_MediaStreamAudioTrack_Attrib</code> for + /// querying. + /// @param[out] value A int32_t for storing the attribute value. + /// + /// @return An int32_t containing a result code from <code>pp_errors.h</code>. + int32_t GetAttrib(PP_MediaStreamAudioTrack_Attrib attrib, + int32_t* value); + + /// Returns the track ID of the underlying MediaStream audio track. + std::string GetId() const; + + /// Checks whether the underlying MediaStream track has ended. + /// Calls to GetBuffer while the track has ended are safe to make and will + /// complete, but will fail. + bool HasEnded() const; + + /// Gets the next audio buffer from the MediaStream track. + /// If internal processing is slower than the incoming buffer rate, + /// new buffers will be dropped from the incoming stream. Once all buffers + /// are full, audio samples will be dropped until <code>RecycleBuffer()</code> + /// is called to free a spot for another buffer. + /// If there are no audio data in the input buffer, + /// <code>PP_OK_COMPLETIONPENDING</code> will be returned immediately and the + /// <code>callback</code> will be called when a new buffer of audio samples + /// is received or some error happens. + /// + /// @param[in] callback A <code>CompletionCallbackWithOutput</code> to be + /// called upon completion of <code>GetBuffer()</code>. If success, + /// an AudioBuffer will be passed into the completion callback function. + /// + /// @return An int32_t containing a result code from <code>pp_errors.h</code>. + int32_t GetBuffer( + const CompletionCallbackWithOutput<AudioBuffer>& callback); + + /// Recycles a buffer returned by <code>GetBuffer()</code>, so the track can + /// reuse the buffer. And the buffer will become invalid. The caller should + /// release all references it holds to <code>buffer</code> and not use it + /// anymore. + /// + /// @param[in] buffer A AudioBuffer returned by <code>GetBuffer()</code>. + /// + /// @return An int32_t containing a result code from <code>pp_errors.h</code>. + int32_t RecycleBuffer(const AudioBuffer& buffer); + + /// Closes the MediaStream audio track, and disconnects it from the audio + /// source. + /// After calling <code>Close()</code>, no new buffers will be received. + void Close(); + + /// Checks whether a <code>Resource</code> is a MediaStream audio track, + /// to test whether it is appropriate for use with the + /// <code>MediaStreamAudioTrack</code> constructor. + /// + /// @param[in] resource A <code>Resource</code> to test. + /// + /// @return True if <code>resource</code> is a MediaStream audio track. + static bool IsMediaStreamAudioTrack(const Resource& resource); +}; + +} // namespace pp + +#endif // PPAPI_CPP_MEDIA_STREAM_AUDIO_TRACK_H_ |