SQL Server on Linux VDI-Client-SDK-Spezifikation

Gilt für:SQL Server unter Linux

In diesem Artikel werden die Schnittstellen behandelt, die vom SQL Server on Linux VDI-Client-SDK (Virtual Device Interface) bereitgestellt werden.

Hinweis

Für SQL Server 2022 (16.x) unter Linux können Sie stattdessen Create a Transact-SQL snapshot backup erstellen.

Unabhängige Softwareanbieter (ISVs) können die Api (Virtual Backup Device Application Programming Interface) verwenden, um SQL Server in ihre Produkte zu integrieren. Im Allgemeinen verhält sich VDI unter Linux ähnlich wie VDI auf Windows mit den folgenden Änderungen:

Windows gemeinsamer Speicher wird zu POSIX gemeinsamem Speicher.
Windows-Semaphoren werden zu POSIX-Semaphoren.
Windows Typen wie HRESULT und DWORD werden in ganzzahlige Entsprechungen geändert.
Die COM-Schnittstellen wurden entfernt und durch C++-Klassen ersetzt.
SQL Server on Linux unterstützt keine benannten Instanzen, sodass Verweise auf den Namen der Instanz entfernt wurden.
Die Shared-Bibliothek wird in libsqlvdi.so implementiert, installiert unter /opt/mssql/lib/libsqlvdi.so.

Dieser Artikel ist ein Zusatz zu Virtual Device Interface (VDI)-Referenz, in dem die SQL Server VDI-Spezifikationen für Windows beschrieben werden.

Überprüfen Sie auch die VDI-Beispielsicherungslösung auf dem SQL Server Samples GitHub Repository.

Einrichten der Benutzerberechtigungen

Unter Linux sind primitive POSIX-Typen dem Benutzer, der sie erstellt, und ihrer Standardgruppe zugeordnet. Bei Objekten, die von SQL Server erstellt werden, gehören diese standardmäßig dem benutzer mssql und der Gruppe mssql. Um die Freigabe zwischen SQL Server und dem VDI-Client zu ermöglichen, wird eine der folgenden beiden Methoden empfohlen:

Führen Sie den VDI-Client als Benutzer mssql aus.

Führen Sie den folgenden Befehl aus, um zum Benutzer mssql zu wechseln:
```
sudo su mssql
```
Fügen Sie den Benutzer mssql der Gruppe vdiuser und den Benutzer vdiuser zur Gruppe mssql hinzu.

Führen Sie die folgenden Befehle aus:
```
sudo useradd vdiuser
sudo usermod -a -G mssql vdiuser
sudo usermod -a -G vdiuser mssql
```
Starten Sie den Server neu, um neue Gruppen für SQL Server und vdiuser aufzunehmen.

Clientfunktionen

In diesem Abschnitt werden die einzelnen Clientfunktionen beschrieben. Die Beschreibungen enthalten die folgenden Informationen:

Zweck der Funktion
Funktionssyntax
Parameterliste
Rückgabewerte
Bemerkungen

ClientVirtualDeviceSet::Create

Zweck

Diese Funktion erstellt den Satz virtueller Geräte.

Syntax

int ClientVirtualDeviceSet::Create (
    char     *    name,    // name for the set
    VDConfig *    cfg      // configuration for the set
);

Parameter

Argument	Erklärung
`name`	Dieser Satz virtueller Geräte wird identifiziert. Die von `CreateFileMapping()` festgelegten Benennungsregeln müssen beachtet werden. Jedes Zeichen außer dem umgekehrten Schrägstrich (`\`) kann verwendet werden. Dies ist eine Zeichenfolge. Es wird empfohlen, der Zeichenfolge den Produkt- oder Firmennamen des Benutzers und den Datenbanknamen voranzustellen.
`cfg`	Dies ist die Konfiguration für den Satz virtueller Geräte.

Rückgabewerte

Argument	Erklärung
`NOERROR`	Die Funktion wurde erfolgreich ausgeführt.
`VD_E_NOTSUPPORTED`	Mindestens ein Feld in der Konfiguration war ungültig oder wurde nicht unterstützt.
`VD_E_PROTOCOL`	Der Satz virtueller Geräte ist bereits vorhanden.

Bemerkungen

Die Create-Methode sollte nur einmal pro BACKUP- oder RESTORE-Vorgang aufgerufen werden. Nachdem die Close-Methode aufgerufen wurde, kann der Client die Schnittstelle wiederverwenden, um eine weitere Gruppe virtueller Geräte zu erstellen.

ClientVirtualDeviceSet::GetConfiguration

Zweck

Diese Funktion wird verwendet, um zu warten, bis der Server das virtuelle Geräteset konfiguriert hat.

Syntax

int ClientVirtualDeviceSet::GetConfiguration (
    time_t        timeout,    // in milliseconds
    VDConfig *    cfg         // selected configuration
);

Parameter

Argument	Erklärung
`timeout`	Dies ist der Timeout in Millisekunden. Mit `INFINITE` oder einer negativen ganzen Zahl können Sie einen Timeout verhindern.
`cfg`	Wenn die Ausführung erfolgreich ist, enthält dieses Argument die vom Server ausgewählte Konfiguration.

Rückgabewerte

Argument	Erklärung
`NOERROR`	Die Konfiguration wurde zurückgegeben.
`VD_E_ABORT`	`SignalAbort` wurde aufgerufen.
`VD_E_TIMEOUT`	Bei der Funktionsausführung ist ein Timeout aufgetreten.

Bemerkungen

Diese Funktion wird im Alertable-Zustand blockiert. Nach dem erfolgreichen Aufruf können die Geräte in der Gruppe virtueller Geräte geöffnet werden.

ClientVirtualDeviceSet::OpenDevice

Zweck

Diese Funktion öffnet eines der Geräte in der Gruppe virtueller Geräte.

Syntax

int ClientVirtualDeviceSet::OpenDevice (
    char                *     name,              // name for the set
    ClientVirtualDevice **    ppVirtualDevice    // returns interface to device
);

Parameter

Argument	Erklärung
`name`	Dieser Satz virtueller Geräte wird identifiziert.
`ppVirtualDevice`	Wenn die Funktion erfolgreich ausgeführt wird, wird ein Zeiger auf das virtuelle Gerät zurückgegeben. Dieses Gerät wird für `GetCommand` und `CompleteCommand` verwendet.

Rückgabewerte

Argument	Erklärung
`NOERROR`	Die Funktion wurde erfolgreich ausgeführt.
`VD_E_ABORT`	Ein Abbruch wurde angefordert.
`VD_E_OPEN`	Alle Geräte sind geöffnet.
`VD_E_PROTOCOL`	Das Set befindet sich nicht im Initialisierungszustand oder dieses bestimmte Gerät ist bereits in Betrieb.
`VD_E_INVALID`	Der Gerätename ist ungültig. Er gehört nicht zu den bekannten Namen der Menge.

Bemerkungen

VD_E_OPEN kann ohne Problem zurückgegeben werden. Der Client kann OpenDevice mithilfe einer Schleife aufrufen, bis dieser Code zurückgegeben wird. Wenn mehr als ein Gerät konfiguriert ist (z. B. n Geräte), werden von der Gruppe virtueller Geräte n eindeutige Geräteschnittstellen zurückgegeben.

Die GetConfiguration-Funktion kann verwendet werden, um solange zu warten, bis sich die Geräte öffnen lassen.

Wenn diese Funktion nicht erfolgreich ausgeführt wird, wird ein NULL-Wert über ppVirtualDevice zurückgegeben.

ClientVirtualDevice::GetCommand

Zweck

Mit dieser Funktion wird der nächste Befehl abgerufen, der sich in der Warteschlange des Geräts befindet. Wenn diese Funktion aufgerufen wird, wartet sie auf den nächsten Befehl.

Syntax

int ClientVirtualDevice::GetCommand (
    time_t           timeout,    // time-out in milliseconds
    VDC_Command**    ppCmd       // returns the next command
);

Parameter

Argument	Erklärung
`timeout`	Dies ist die Wartezeit in Millisekunden. Mit `INFINITE` oder einem negativen Wert legen Sie eine unbegrenzte Wartezeit fest. Verwenden Sie `0`, um nach einem Befehl zu fragen. `VD_E_TIMEOUT` wird zurückgegeben, wenn aktuell kein Befehl verfügbar ist. Wenn der Timeout auftritt, entscheidet der Client, welche Aktion als Nächstes ausgeführt wird.
`ppCmd`	Wenn ein Befehl erfolgreich zurückgegeben wird, gibt der Parameter die Adresse eines auszuführenden Befehls zurück. Der zurückgegebene Speicher ist schreibgeschützt. Nachdem der Befehl abgeschlossen wurde, wird dieser Zeiger der `CompleteCommand`-Routine übergeben.

Rückgabewerte

Argument	Erklärung
`NOERROR`	Ein Befehl wurde abgerufen.
`VD_E_CLOSE`	Das Gerät wurde vom Server geschlossen.
`VD_E_TIMEOUT`	Es war kein Befehl verfügbar, und der Timeout ist abgelaufen.
`VD_E_ABORT`	Entweder der Client oder der Server hat mit `SignalAbort` das Herunterfahren erzwungen.

Bemerkungen

Wenn VD_E_CLOSE zurückgegeben wird, hat SQL Server das Gerät geschlossen. Dies ist Teil des normalen Herunterfahrens. Nachdem alle Geräte geschlossen wurden, ruft der Client ClientVirtualDeviceSet::Close auf, um die Gruppe virtueller Geräte zu schließen. Wenn diese Routine blockiert werden muss, um auf einen Befehl zu warten, wird der Thread in den Alertable-Zustand versetzt.

ClientVirtualDevice::CompleteCommand

Zweck

Diese Funktion wird verwendet, um SQL Server darüber zu benachrichtigen, dass ein Befehl abgeschlossen ist. Für den Befehl sollten geeignete Vervollständigungsinformationen zurückgegeben werden.

Syntax

int ClientVirtualDevice::CompleteCommand (
    VDC_Command      pCmd,                // the command
    int              completionCode,      // completion code
    unsigned long    bytesTransferred,    // bytes transferred
    int64_t          position             // current position
);

Parameter

Argument	Erklärung
`pCmd`	Dies ist die Adresse eines Befehls, der vorher von `ClientVirtualDevice::GetCommand` zurückgegeben wurde.
`completionCode`	Dies ist ein Statuscode, der den Abschlussstatus angibt. Dieser Parameter muss für alle Befehle zurückgegeben werden. Der zurückgegebene Code sollte für den Befehl geeignet sein, der ausgeführt wird. `ERROR_SUCCESS` wird immer verwendet, um einen erfolgreich ausgeführten Befehl anzugeben. Eine vollständige Liste der möglichen Codes finden Sie in der Datei `vdierror.h`.
`bytesTransferred`	Dies ist die Anzahl der erfolgreich übertragenen Bytes. Dieses Argument wird nur für die Datenübertragungsbefehle `Read` und `Write` zurückgegeben.
`position`	Dies ist ausschließlich eine Antwort auf den `GetPosition`-Befehl.

Rückgabewerte

Argument	Erklärung
`NOERROR`	Der Abschluss wurde korrekt erfasst.
`VD_E_INVALID`	`pCmd` war kein aktiver Befehl.
`VD_E_ABORT`	`Abort` wurde angezeigt.
`VD_E_PROTOCOL`	Das Gerät ist nicht geöffnet.

Bemerkungen

Keine

ClientVirtualDeviceSet::SignalAbort

Zweck

Mit dieser Funktion wird angegeben, dass ein Vorgang unplanmäßig beendet werden soll.

Syntax

int ClientVirtualDeviceSet::SignalAbort ();

Parameter

Argument	Erklärung
Keine	Nicht zutreffend

Rückgabewerte

Argument	Erklärung
`NOERROR`	Die `Abort`-Benachrichtigung wurde erfolgreich bereitgestellt.

Bemerkungen

Der Client kann jederzeit den Vorgang BACKUP oder RESTORE abbrechen. Mit dieser Routine wird angegeben, dass alle Vorgänge beendet werden sollen. Die gesamte Gruppe virtueller Geräte wird in den Zustand Abnormally Terminated versetzt. Auf keinem Gerät werden weitere Befehle zurückgegeben. Alle nicht abgeschlossenen Befehle werden automatisch abgeschlossen. Als Abschlusscode wird ERROR_OPERATION_ABORTED zurückgegeben. Sobald der Client jegliche verbleibende Nutzung von ihm bereitgestellten Puffern sicher beendet hat, sollte er ClientVirtualDeviceSet::Close aufrufen.

ClientVirtualDeviceSet::Close

Zweck

Diese Funktion schließt die Gruppe virtueller Geräte, die von ClientVirtualDeviceSet::Create erstellt wurde. Dadurch werden alle Ressourcen freigegeben, die der Gruppe virtueller Geräte zugeordnet sind.

Syntax

int ClientVirtualDeviceSet::Close ();

Parameter

Argument	Erklärung
Keine	Nicht zutreffend

Rückgabewerte

Argument	Erklärung
`NOERROR`	Dies wird zurückgegeben, wenn der virtuelle Gerätesatz erfolgreich geschlossen wurde.
`VD_E_PROTOCOL`	Es wurde keine Aktion ausgeführt, weil das virtuelle Gerätset nicht geöffnet war.
`VD_E_OPEN`	Die Geräte waren noch geöffnet.

Bemerkungen

Wenn der Client Close aufruft, wird damit darauf hingewiesen, dass alle Ressourcen, die von der Gruppe virtueller Geräte genutzt werden, freigegeben werden sollten. Der Client muss sicherstellen, dass alle Aktivitäten, die Datenpuffer und virtuelle Geräte betreffen, vor dem Aufrufen von Close beendet werden. Dies liegt daran, dass durch OpenDevice sämtliche von Close zurückgegebenen Schnittstellen virtueller Geräte ungültig werden.

Der Client hat die Erlaubnis, nach der Rückgabe des Create-Aufrufs einen Close-Aufruf an die Schnittstelle für die Gruppe virtueller Geräte zu senden. Durch einen solchen Aufruf wird eine neue virtuelle Gerätegruppe für einen nachfolgenden BACKUP- oder RESTORE-Vorgang erstellt.

Wenn Close aufgerufen wird und noch mindestens ein virtuelles Gerät geöffnet ist, wird VD_E_OPEN zurückgegeben. In diesem Fall wird SignalAbort intern ausgelöst, um nach Möglichkeit ein ordnungsgemäßes Herunterfahren zu gewährleisten. Dabei werden VDI-Ressourcen freigegeben. Der Client sollte auf einen VD_E_CLOSE-Hinweis auf jedem Gerät warten, bevor er ClientVirtualDeviceSet::Close aufruft. Wenn dem Client bekannt ist, dass sich die Gruppe virtueller Geräte bereits im Zustand Abnormally Terminated befindet, sollte der Client nicht annehmen, dass die Angabe VD_E_CLOSE von GetCommand übermittelt wird. Der Client hat die Möglichkeit, ClientVirtualDeviceSet::Close aufzurufen, sobald die Aktivität im Zusammenhang mit den gemeinsam verwendeten Puffern beendet wird.

ClientVirtualDeviceSet::OpenInSecondary

Zweck

Mit dieser Funktion wird das virtuelle Geräteset in einem sekundären Client geöffnet. Der primäre Client muss vorher bereits Create und GetConfiguration verwendet haben, um die virtuelle Gerätegruppe einzurichten.

Syntax

int ClientVirtualDeviceSet::OpenInSecondary (
    char *    setName    // name of the set
);

Parameter

Argument	Erklärung
`setName`	Mit diesem Argument wird die Gruppe identifiziert. Die Groß- und Kleinschreibung dieses Namens muss beachtet werden. Der Name muss außerdem mit dem Namen übereinstimmen, der vom primären Client beim Aufruf von `ClientVirtualDeviceSet::Create` verwendet wurde.

Rückgabewerte

Argument	Erklärung
`NOERROR`	Die Funktion wurde erfolgreich ausgeführt.
`VD_E_PROTOCOL`	Die virtuelle Gerätegruppe wurde noch nicht erstellt, wurde bereits für diesen Client geöffnet oder ist noch nicht bereit, Öffnungsanforderungen von sekundären Clients zu akzeptieren.
`VD_E_ABORT`	Der Vorgang wird abgebrochen.

Hinweise: Wenn ein Modell mit mehreren Prozessen genutzt wird, ist der primäre Client dafür verantwortlich, eine planmäßige und unplanmäßige Beendigung der sekundären Clients zu erkennen.

ClientVirtualDeviceSet::GetBufferHandle

Zweck

Für einige Anwendungen sind möglicherweise mehrere Prozesse erforderlich, damit Puffer verarbeitet werden können, die von ClientVirtualDevice::GetCommand zurückgegeben werden. In solchen Fällen kann der Prozess, der den Befehl empfängt, GetBufferHandle verwenden, um ein prozessunabhängiges Handle abzurufen, das den Puffer identifiziert. Dieses Handle kann dann jedem anderen Prozess mitgeteilt werden, der ebenfalls dieselbe Gruppe virtueller Geräte geöffnet hat. Dieser Vorgang würde dann ClientVirtualDeviceSet::MapBufferHandle zum Abrufen der Adresse des Puffers verwenden. Bei der Adresse handelt es sich wahrscheinlich um eine andere Adresse als die im zugehörigen Partnerprozess, da jeder Prozess verschiedene Adressen verwenden kann, um Puffer zuzuordnen.

Syntax

int ClientVirtualDeviceSet::GetBufferHandle (
    uint8_t*         pBuffer,         // in: buffer address
    unsigned int*    pBufferHandle    // out: buffer handle
);

Parameter

Argument	Erklärung
`pBuffer`	Dies ist die Adresse eines Puffers, der mit einem `Read`- oder `Write`-Befehl abgerufen wurde.
`BufferHandle`	Ein eindeutiger Bezeichner für den Puffer wird zurückgegeben.

Rückgabewerte

Argument	Erklärung
`NOERROR`	Die Funktion wurde erfolgreich ausgeführt.
`VD_E_PROTOCOL`	Das virtuelle Geräteset ist derzeit nicht geöffnet.
`VD_E_INVALID`	Der `pBuffer` ist keine gültige Adresse.

Bemerkungen

Der Prozess, der die Funktion GetBufferHandle aufruft, ist auch für den Aufruf von ClientVirtualDevice::CompleteCommand verantwortlich, nachdem die Datenübertragung abgeschlossen wurde.

ClientVirtualDeviceSet::MapBufferHandle

Zweck

Mit dieser Funktion wird eine Adresse eines gültigen Puffers aus einem Pufferhandle abgerufen, das wiederum aus einem anderen Prozess abgerufen wurde.

Syntax

int ClientVirtualDeviceSet::MapBufferHandle (
    int          dwBuffer,    // in: buffer handle
    uint8_t**    ppBuffer     // out: buffer address
);

Parameter

Argument	Erklärung
`dwBuffer`	Dies ist das von `ClientVirtualDeviceSet::GetBufferHandle` zurückgegebene Handle.
`ppBuffer`	Dies ist die Adresse des Puffers, die im aktuellen Prozess gültig ist.

Rückgabewerte

Argument	Erklärung
`NOERROR`	Die Funktion wurde erfolgreich ausgeführt.
`VD_E_PROTOCOL`	Das virtuelle Geräteset ist derzeit nicht geöffnet.
`VD_E_INVALID`	`ppBuffer` ist ein ungültiges Handle.

Bemerkungen

Achten Sie darauf, die Handles korrekt zu kommunizieren. Griffe sind lokal auf eine einzelne Gruppe virtueller Geräte beschränkt. Die Partnerprozesse, die ein Handle gemeinsam nutzen, müssen sicherstellen, dass Puffer-Handles nur innerhalb des Bereichs der virtuellen Geräteliste verwendet werden, aus der der Puffer ursprünglich abgerufen wurde.

Feedback

War diese Seite hilfreich?

Last updated on 2026-04-13

SQL Server on Linux VDI-Client-SDK-Spezifikation

Einrichten der Benutzerberechtigungen

Clientfunktionen

ClientVirtualDeviceSet::Create

Zweck

Syntax

Parameter

Rückgabewerte

Bemerkungen

ClientVirtualDeviceSet::GetConfiguration

Zweck

Syntax

Parameter

Rückgabewerte

Bemerkungen

ClientVirtualDeviceSet::OpenDevice

Zweck

Syntax

Parameter

Rückgabewerte

Bemerkungen

ClientVirtualDevice::GetCommand

Zweck

Syntax

Parameter

Rückgabewerte

Bemerkungen

ClientVirtualDevice::CompleteCommand

Zweck

Syntax

Parameter

Rückgabewerte

Bemerkungen

ClientVirtualDeviceSet::SignalAbort

Zweck

Syntax

Parameter

Rückgabewerte

Bemerkungen

ClientVirtualDeviceSet::Close

Zweck

Syntax

Parameter

Rückgabewerte

Bemerkungen

ClientVirtualDeviceSet::OpenInSecondary

Zweck

Syntax

Parameter

Rückgabewerte

ClientVirtualDeviceSet::GetBufferHandle

Zweck

Syntax

Parameter

Rückgabewerte

Bemerkungen

ClientVirtualDeviceSet::MapBufferHandle

Zweck

Syntax

Parameter

Rückgabewerte

Bemerkungen

Feedback

Zusätzliche Ressourcen