SDK-Rückrufe von Produzenten

Die Klassen und Methoden im Amazon Kinesis Video Streams Producer SDK verwalten keine eigenen Prozesse. Sie verwenden stattdessen eingehende Funktionsaufrufe und Ereignisse, um Callbacks für die Kommunikation mit der Anwendung zu planen.

Es gibt zwei Callback-Mustern, die die Anwendung für die Interaktion mit dem SDK verwenden kann:

• CallbackProvider— Dieses Objekt macht jeden Callback von der PIC-Komponente (Platform-Independent Code) für die Anwendung verfügbar. Dieses Muster ermöglicht eine umfassende Funktionalität, bedeutet jedoch auch, dass die Implementierung alle öffentlichen API-Methoden und -Signaturen auf C++-Ebene verarbeiten muss.

• StreamCallbackProviderund ClientCallbackProvider — Diese Objekte machen die stream- und clientspezifischen Callbacks verfügbar, und die C++-Schicht des SDK macht die restlichen Callbacks verfügbar. Dies ist das empfohlene Callback-Muster für die Interaktion mit dem Producer SDK.

In der folgenden Abbildung ist das Objektmodell der Callback-Objekte dargestellt:

In der vorherigen Abbildung ist DefaultCallbackProvider von CallbackProvider abgeleitet (der alle Callbacks im PIC bereitstellt) und enthält StreamCallbackProvider und ClientCallbackProvider.

ClientCallbackProvider

Das ClientCallbackProvider -Objekt stellt Callback-Funktionen auf Client-Ebene bereit. Die Details der Funktionen sind im Abschnitt ClientCallbacks beschrieben.

Callback-Methoden:

• getClientReadyCallback— Meldet einen Bereitschaftsstatus für den Client.

• getStorageOverflowPressureCallback— Meldet einen Speicherüberlauf oder -druck. Dieser Callback wird aufgerufen, wenn die Speichernutzung den Wert STORAGE_PRESSURE_NOTIFICATION_THRESHOLD, also 5 Prozent der Gesamtspeichergröße, unterschreitet. Weitere Informationen finden Sie unter StorageInfo.

StreamCallbackProvider

Das StreamCallbackProvider -Objekt stellt Callback-Funktionen auf Stream-Ebene bereit.

Callback-Methoden:

• getDroppedFragmentReportCallback: Meldet ein verworfenes Fragment.

• getDroppedFrameReportCallback— Meldet einen verlorenen Frame.

• getFragmentAckReceivedCallback— Meldet, dass ein Fragment-ACK für den Stream empfangen wurde.

• getStreamClosedCallback— Meldet einen Zustand, in dem der Stream geschlossen ist.

• getStreamConnectionStaleCallback— Meldet einen veralteten Verbindungszustand. In diesem Zustand sendet der Hersteller Daten an den Dienst, erhält jedoch keine Bestätigungen.

• getStreamDataAvailableCallback— Meldet, dass Daten im Stream verfügbar sind.

• getStreamErrorReportCallback— Meldet einen Stream-Fehler.

• getStreamLatencyPressureCallback— Meldet einen Zustand der Stream-Latenz, wenn die kumulierte Puffergröße größer als der max_latency Wert ist. Weitere Informationen finden Sie unter StreamDefinition/StreamInfo.

• getStreamReadyCallback: — Meldet einen Zustand, in dem der Stream bereit ist.

• getStreamUnderflowReportCallback— Meldet einen Zustand, in dem der Stream unterläuft. Diese Funktion wird derzeit nicht verwendet und ist für die future Verwendung reserviert.

Den Quellcode für finden Sie StreamCallbackProvider unter StreamCallbackProvider.h.

ClientCallbacks Struktur

Die Struktur ClientCallbacks enthält die Callback-Funktionseingangspunkte, die der PIC aufruft, wenn spezielle Ereignisse auftreten. Die Struktur enthält auch Versionsinformationen im Feld CALLBACKS_CURRENT_VERSION sowie das Feld customData mit benutzerdefinierten Daten, die für einzelne Callback-Funktionen zurückgegeben werden.

Die Client-Anwendung kann einen this-Zeiger für das Feld custom_data verwenden, um Mitgliedsfunktionen den statischen ClientCallback-Funktionen während der Laufzeit zuzuweisen, wie im folgenden Codebeispiel gezeigt:

STATUS TestStreamCallbackProvider::streamClosedHandler(UINT64 custom_data, STREAM_HANDLE stream_handle, UINT64 stream_upload_handle) {
    LOG_INFO("Reporting stream stopped.");

TestStreamCallbackProvider* streamCallbackProvider = reinterpret_cast<TestStreamCallbackProvider*> (custom_data);
streamCallbackProvider->streamClosedHandler(...);

Ereignisse
Funktion	Beschreibung	Typ
CreateDeviceFunc	Derzeit nicht im Backend implementiert. Dieser Aufruf schlägt fehl, wenn er mit Java oder C++ ausgeführt wird. Andere Clients führen eine plattformspezifische Initialisierung durch.	Backend API
CreateStreamFunc	Wird beim Erstellen des Streams aufgerufen	Backend API
DescribeStreamFunc	Wird aufgerufen, wenn DescribeStream aufgerufen wird	Backend API
GetStreamingEndpointFunc	Wird aufgerufen, wenn GetStreamingEndpoint aufgerufen wird	Backend API
GetStreamingTokenFunc	Wird aufgerufen, wenn GetStreamingToken aufgerufen wird	Backend API
PutStreamFunc	Wird aufgerufen, wenn PutStream aufgerufen wird	Backend API
TagResourceFunc	Wird aufgerufen, wenn TagResource aufgerufen wird	Backend API
CreateMutexFunc	Erstellt einen Synchronisierungs-Mutex.	Synchronisierung
FreeMutexFunc	Gibt den Mutex frei.	Synchronisierung
LockMutexFunc	Sperrt den Synchronisierungs-Mutex.	Synchronisierung
TryLockMutexFunc	Versucht den Mutex zu sperren. Derzeit nicht implementiert.	Synchronisierung
UnlockMutexFunc	Hebt die Sperrung des Mutex auf.	Synchronisierung
ClientReadyFunc	Wird aufgerufen, wenn der Client bereit ist.	Benachrichtigung
DroppedFrameReportFunc	Meldet, wenn ein Frame verworfen wird.	Benachrichtigung
DroppedFragmentReportFunc	Meldet, wenn ein Fragment verworfen wird. Diese Funktion wird derzeit nicht verwendet und ist für die future Verwendung reserviert.	Benachrichtigung
FragmentAckReceivedFunc	Wird aufgerufen, wenn eine Fragment-ACK (Puffern, Empfang, persistent und Fehler) empfangen wird.	Benachrichtigung
StorageOverflowPressureFunc	Wird aufgerufen, wenn die Speichernutzung den Wert STORAGE_PRESSURE_NOTIFICATION_THRESHOLD, also 5 Prozent der Gesamtspeichergröße, unterschreitet.	Benachrichtigung
StreamClosedFunc	Wird aufgerufen, wenn die letzten Bits der verbleibenden Frames gestreamt werden.	Benachrichtigung
StreamConnectionStaleFunc	Wird aufgerufen, wenn der Stream veraltet ist. In diesem Fall sendet der Produzent Daten an den Service, empfängt jedoch keine Bestätigungen.	Benachrichtigung
StreamDataAvailableFunc	Wird aufgerufen, wenn Stream-Daten verfügbar sind.	Benachrichtigung
StreamErrorReportFunc	Wird aufgerufen, wenn ein Stream-Fehler auftritt. Der PIC schließt den Stream in diesem Fall automatisch.	Benachrichtigung
StreamLatencyPressureFunc	Wird aufgerufen, wenn der Stream latent ist, d. h. die kumulierte Puffergröße den Wert max_latency überschreitet. Weitere Informationen finden Sie unter StreamDefinition/StreamInfo.	Benachrichtigung
StreamReadyFunc	Wird aufgerufen, wenn der Stream bereit ist.	Benachrichtigung
StreamUnderflowReportFunc	Diese Funktion wird derzeit nicht verwendet und ist für die future Verwendung reserviert.	Benachrichtigung
DeviceCertToTokenFunc	Gibt das Verbindungszertifikat als Token zurück.	Plattformintegration
GetCurrentTimeFunc	Gibt die aktuelle Zeit zurück.	Plattformintegration
GetDeviceCertificateFunc	Gibt das Gerätezertifikat zurück. Diese Funktion wird derzeit nicht verwendet und ist für die future Verwendung reserviert.	Plattformintegration
GetDeviceFingerprintFunc	Gibt die Geräteidentifikation zurück. Diese Funktion wird derzeit nicht verwendet und ist für die future Verwendung reserviert.	Plattformintegration
GetRandomNumberFunc	Gibt eine zufällige Zahl zwischen 0 und RAND_MAX zurück.	Plattformintegration
GetSecurityTokenFunc	Gibt das Sicherheitstoken zurück, das an die Funktionen übergeben wurde, die mit der Backend-API kommunizieren. Die Implementierung kann die serialisierten Werte für AccessKeyId, SecretKeyId und das Sitzungstoken angeben.	Plattformintegration
LogPrintFunc	Protokolliert eine Textzeile mit dem Tag und der Protokollebene. Weitere Informationen finden Sie unter PlatformUtils.h.	Plattformintegration

Für die Plattformintegrationsfunktionen aus der vorherigen Tabelle ist der letzte Parameter eine ServiceCallContext-Struktur mit den folgenden Feldern:

• version: Die Version der Struktur

• callAfter: Eine absolute Zeit, nach der die Funktion aufgerufen wird

• timeout: Die Zeitüberschreitung der Operation in Einheiten von 100 Nanosekunden

• customData: Ein benutzerdefinierter Wert, der an den Client übergeben wird

• pAuthInfo: Die Anmeldeinformationen für den Aufruf. Weitere Informationen finden Sie in der folgenden (__AuthInfo)-Struktur.

Die Autorisierungsinformationen werden mit der Struktur __AuthInfo bereitgestellt. Diese kann entweder serialisierte Anmeldeinformationen oder ein anbieterspezifisches Authentifizierungstoken enthalten. Diese Struktur enthält die folgenden Felder:

• version: Die Version der __AuthInfo-Struktur

• type: Ein AUTH_INFO_TYPE-Wert, über den der Typ der Anmeldeinformationen (Zertifikat oder Sicherheitstoken) definiert wird

• data: Ein Byte-Array mit den Authentifizierungsinformationen

• size: Die Größe des data-Parameters

• expiration: Die Ablaufdauer der Anmeldeinformationen in Einheiten von 100 Nanosekunden

Callback-Implementierungen, um das Streaming erneut zu versuchen

Das Kinesis Video Producer-SDK gibt über Callback-Funktionen den Streaming-Status an. Es wird empfohlen, die folgenden Callback-Mechanismen zu implementieren, um bei vorübergehenden Netzwerkproblemen, die während des Streamings aufgetreten sind, die Wiederherstellung zu gewährleisten.

• Stream-Latenzdruck-Callback — Dieser Callback-Mechanismus wird ausgelöst, wenn das SDK auf eine Stream-Latenz stößt. Dies geschieht, wenn die kumulierte Puffergröße größer ist als der MAX_LATENCY-Wert. Wenn der Stream erstellt wurde, legt die Streaming-Anwendung MAX_LATENCY auf den Standardwert von 60 Sekunden fest. Die typische Implementierung für diesen Callback besteht darin, die Verbindung zurückzusetzen. Sie können die Beispielimplementierung unter https://github.com/awslabs/ amazon-kinesis-video-streams — producer-sdk-cpp /blob/master/ kinesis-video-c-producer /src/source/ .c nach Bedarf verwenden. StreamLatencyStateMachine Beachten Sie, dass es keine Möglichkeit gibt, Frames, die aufgrund eines Netzwerkausfalls nicht zugestellt wurden, in einem sekundären Speicher zu speichern, um sie wieder aufzufüllen.

• Stream-Staleness-Callback — Dieser Callback wird ausgelöst, wenn der Producer Daten an den Amazon Kinesis Data Streams Streams-Service (Uplink) senden kann, aber die Bestätigungen (gepuffertes ACK) nicht rechtzeitig zurückholen kann (Standard ist 60 Sekunden). Abhängig von den Netzwerkeinstellungen kann entweder der Stream-Latenzdruck-Callback oder der Stream-Staleness-Callback oder beide initiiert werden. Ähnlich wie bei der Wiederholungsversuchimplementierung des Callbacks für Stream-Latenzdruck besteht die typische Implementierung darin, die Verbindung zurückzusetzen und eine neue Verbindung für das Streaming zu starten. Sie können die Beispielimplementierung unter https://github.com/awslabs/ amazon-kinesis-video-streams ConnectionStaleStateMachine -producer-c/blob/master/src/source/ .c nach Bedarf verwenden.

• Stream-Fehler-Callback — Dieser Callback wird ausgelöst, wenn das SDK beim Aufruf der KVS-API-Serviceaufrufen auf einen Timeout bei der Netzwerkverbindung oder auf andere Fehler stößt.

• Abgebrochener Frame-Callback — dieser Callback wird ausgelöst, wenn der Speicherplatz voll ist, entweder aufgrund einer langsamen Netzwerkgeschwindigkeit oder eines Streamfehlers. Wenn die Netzwerkgeschwindigkeit dazu führt, dass Frames verloren gehen, können Sie entweder die Speichergröße erhöhen, die Videobildgröße reduzieren oder die Bildrate an die Netzwerkgeschwindigkeit anpassen.