blob: 1865ea62c513a57c77a370a0fb358b84c709ca9f [file] [log] [blame]
Benjamin Wright00765292018-12-01 00:18:261/*
2 * Copyright (c) 2018 The WebRTC project authors. All Rights Reserved.
3 *
4 * Use of this source code is governed by a BSD-style license
5 * that can be found in the LICENSE file in the root of the source
6 * tree. An additional intellectual property rights grant can be found
7 * in the file PATENTS. All contributing project authors may
8 * be found in the AUTHORS file in the root of the source tree.
9 */
10
11#ifndef VIDEO_BUFFERED_FRAME_DECRYPTOR_H_
12#define VIDEO_BUFFERED_FRAME_DECRYPTOR_H_
13
14#include <deque>
15#include <memory>
16
Steve Anton10542f22019-01-11 17:11:0017#include "api/crypto/crypto_options.h"
18#include "api/crypto/frame_decryptor_interface.h"
Jonas Orelande62c2f22022-03-29 09:04:4819#include "api/field_trials_view.h"
Tony Herrebe9b5762023-02-03 11:29:0420#include "modules/rtp_rtcp/source/frame_object.h"
Benjamin Wright00765292018-12-01 00:18:2621
22namespace webrtc {
23
24// This callback is provided during the construction of the
25// BufferedFrameDecryptor and is called each time a frame is sucessfully
26// decrypted by the buffer.
27class OnDecryptedFrameCallback {
28 public:
29 virtual ~OnDecryptedFrameCallback() = default;
30 // Called each time a decrypted frame is returned.
philipelca188092021-03-23 11:00:4931 virtual void OnDecryptedFrame(std::unique_ptr<RtpFrameObject> frame) = 0;
Benjamin Wright00765292018-12-01 00:18:2632};
33
Benjamin Wright52426ed2019-03-01 19:01:5934// This callback is called each time there is a status change in the decryption
35// stream. For example going from a none state to a first decryption or going
36// frome a decryptable state to a non decryptable state.
37class OnDecryptionStatusChangeCallback {
38 public:
39 virtual ~OnDecryptionStatusChangeCallback() = default;
40 // Called each time the decryption stream status changes. This call is
41 // blocking so the caller must relinquish the callback quickly. This status
42 // must match what is specified in the FrameDecryptorInterface file. Notably
43 // 0 must indicate success and any positive integer is a failure.
Benjamin Wright2af5dcb2019-04-09 20:08:4144 virtual void OnDecryptionStatusChange(
45 FrameDecryptorInterface::Status status) = 0;
Benjamin Wright52426ed2019-03-01 19:01:5946};
47
Benjamin Wright00765292018-12-01 00:18:2648// The BufferedFrameDecryptor is responsible for deciding when to pass
49// decrypted received frames onto the OnDecryptedFrameCallback. Frames can be
50// delayed when frame encryption is enabled but the key hasn't arrived yet. In
51// this case we stash about 1 second of encrypted frames instead of dropping
52// them to prevent re-requesting the key frame. This optimization is
53// particularly important on low bandwidth networks. Note stashing is only ever
54// done if we have never sucessfully decrypted a frame before. After the first
55// successful decryption payloads will never be stashed.
56class BufferedFrameDecryptor final {
57 public:
58 // Constructs a new BufferedFrameDecryptor that can hold
59 explicit BufferedFrameDecryptor(
60 OnDecryptedFrameCallback* decrypted_frame_callback,
Jonas Oreland8ca06132022-03-14 11:52:4861 OnDecryptionStatusChangeCallback* decryption_status_change_callback,
Jonas Orelande62c2f22022-03-29 09:04:4862 const FieldTrialsView& field_trials);
Jonas Oreland8ca06132022-03-14 11:52:4863
Benjamin Wright00765292018-12-01 00:18:2664 ~BufferedFrameDecryptor();
65 // This object cannot be copied.
66 BufferedFrameDecryptor(const BufferedFrameDecryptor&) = delete;
67 BufferedFrameDecryptor& operator=(const BufferedFrameDecryptor&) = delete;
Benjamin Wrighta5564482019-04-03 17:44:1868
69 // Sets a new frame decryptor as the decryptor for the buffered frame
70 // decryptor. This allows the decryptor to be switched out without resetting
71 // the video stream.
72 void SetFrameDecryptor(
73 rtc::scoped_refptr<FrameDecryptorInterface> frame_decryptor);
74
Benjamin Wright00765292018-12-01 00:18:2675 // Determines whether the frame should be stashed, dropped or handed off to
76 // the OnDecryptedFrameCallback.
philipelca188092021-03-23 11:00:4977 void ManageEncryptedFrame(std::unique_ptr<RtpFrameObject> encrypted_frame);
Benjamin Wright00765292018-12-01 00:18:2678
79 private:
80 // Represents what should be done with a given frame.
81 enum class FrameDecision { kStash, kDecrypted, kDrop };
82
83 // Attempts to decrypt the frame, if it fails and no prior frames have been
84 // decrypted it will return kStash. Otherwise fail to decrypts will return
85 // kDrop. Successful decryptions will always return kDecrypted.
philipelca188092021-03-23 11:00:4986 FrameDecision DecryptFrame(RtpFrameObject* frame);
Benjamin Wright00765292018-12-01 00:18:2687 // Retries all the stashed frames this is triggered each time a kDecrypted
88 // event occurs.
89 void RetryStashedFrames();
90
91 static const size_t kMaxStashedFrames = 24;
92
Benjamin Wright168456c2018-12-07 19:31:2593 const bool generic_descriptor_auth_experiment_;
Benjamin Wright00765292018-12-01 00:18:2694 bool first_frame_decrypted_ = false;
Benjamin Wright2af5dcb2019-04-09 20:08:4195 FrameDecryptorInterface::Status last_status_ =
96 FrameDecryptorInterface::Status::kUnknown;
Benjamin Wrighta5564482019-04-03 17:44:1897 rtc::scoped_refptr<FrameDecryptorInterface> frame_decryptor_;
Benjamin Wright00765292018-12-01 00:18:2698 OnDecryptedFrameCallback* const decrypted_frame_callback_;
Benjamin Wright52426ed2019-03-01 19:01:5999 OnDecryptionStatusChangeCallback* const decryption_status_change_callback_;
philipelca188092021-03-23 11:00:49100 std::deque<std::unique_ptr<RtpFrameObject>> stashed_frames_;
Benjamin Wright00765292018-12-01 00:18:26101};
102
103} // namespace webrtc
104
105#endif // VIDEO_BUFFERED_FRAME_DECRYPTOR_H_