specyfikacja zestawu SDK klienta SQL Server on Linux VDI

Applies to:SQL Server w systemie Linux

W tym artykule opisano interfejsy udostępniane przez zestaw SDK klienta dla interfejsu urządzeń wirtualnych (VDI) SQL Server na systemie Linux.

Notatka

W przypadku SQL Server 2022 (16.x) na systemie Linux możesz zamiast tego utworzyć kopię zapasową migawki Transact-SQL.

Niezależni dostawcy oprogramowania mogą integrować SQL Server z ich produktami za pomocą interfejsu API (Virtual Backup Device Application Programming Interface). Ogólnie rzecz biorąc, VDI w systemie Linux zachowuje się podobnie do VDI w Windows z następującymi zmianami:

Udostępniona pamięć Windows staje się pamięcią współdzieloną POSIX.
Windows semafory stają się semaforami POSIX.
Typy systemu Windows, takie jak HRESULT i DWORD, są zmieniane na odpowiedniki liczb całkowitych.
Interfejsy COM są usuwane i zastępowane parą klas języka C++.
SQL Server on Linux nie obsługuje nazwanych wystąpień, dlatego odwołania do nazwy wystąpienia zostały usunięte.
Biblioteka udostępniona jest zaimplementowana w libsqlvdi.so, zainstalowana w /opt/mssql/lib/libsqlvdi.so.

Ten artykuł jest dodatkiem do Dokumentacja interfejsu urządzenia wirtualnego (VDI), która zawiera szczegółowe informacje na temat specyfikacji interfejsu VDI SQL Server w Windows.

Proszę sprawdzić również przykładowe rozwiązanie do tworzenia kopii zapasowych VDI w repozytorium SQL Server Samples GitHub.

Konfiguracja uprawnień użytkownika

W systemie Linux elementy pierwotne POSIX są własnością użytkownika tworzącego je i ich grupę domyślną. W przypadku obiektów utworzonych przez SQL Server są one domyślnie własnością użytkownika mssql i grupy mssql. Aby umożliwić udostępnianie między SQL Server a klientem VDI, zaleca się użycie jednej z następujących dwóch metod:

Uruchom klienta VDI jako użytkownika mssql.

Wykonaj następujące polecenie, aby przełączyć się na użytkownika mssql:
```
sudo su mssql
```
Dodaj użytkownika mssql do grupy vdiuser, a użytkownik vdiuser do grupy mssql.

Wykonaj następujące polecenia:
```
sudo useradd vdiuser
sudo usermod -a -G mssql vdiuser
sudo usermod -a -G vdiuser mssql
```
Uruchom ponownie serwer, aby pobrać nowe grupy dla SQL Server i vdiuser.

Funkcje klienta

Ta sekcja zawiera opisy poszczególnych funkcji klienta. Opisy zawierają następujące informacje:

Cel funkcji
Składnia funkcji
Lista parametrów
Zwracane wartości
Uwagi

ClientVirtualDeviceSet::Create

Cel

Ta funkcja tworzy zestaw urządzeń wirtualnych.

Składnia

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

Parametry

Argument/kłótnia	Wyjaśnienie
`name`	Spowoduje to zidentyfikowanie zestawu urządzeń wirtualnych. Należy przestrzegać reguł nazw używanych przez `CreateFileMapping()`. Może być używany dowolny znak z wyjątkiem backslash (`\`). Jest to ciąg znaków. Zaleca się poprzedzanie ciągu nazwą produktu lub firmy użytkownika i nazwą bazy danych.
`cfg`	Jest to konfiguracja zestawu urządzeń wirtualnych.

Zwracane wartości

Argument/kłótnia	Wyjaśnienie
`NOERROR`	Funkcja zakończyła się pomyślnie.
`VD_E_NOTSUPPORTED`	Co najmniej jedno pole w konfiguracji było nieprawidłowe lub w inny sposób nieobsługiwane.
`VD_E_PROTOCOL`	Zestaw urządzeń wirtualnych już istnieje.

Uwagi

Metoda Create powinna być wywoływana tylko raz na operację BACKUP lub RESTORE. Po wywołaniu metody Close klient może ponownie użyć interfejsu, aby utworzyć inny zestaw urządzeń wirtualnych.

ClientVirtualDeviceSet::GetConfiguration

Cel

Ta funkcja służy do oczekiwania na skonfigurowanie zestawu urządzeń wirtualnych przez serwer.

Składnia

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

Parametry

Argument/kłótnia	Wyjaśnienie
`timeout`	Jest to limit czasu w milisekundach. Użyj `INFINITE` lub dowolnej ujemnej liczby całkowitej, aby zapobiec przekroczeniu limitu czasu.
`cfg`	Po pomyślnym wykonaniu zawiera konfigurację wybraną przez serwer.

Zwracane wartości

Argument/kłótnia	Wyjaśnienie
`NOERROR`	Konfiguracja została zwrócona.
`VD_E_ABORT`	`SignalAbort` zostało wywołane.
`VD_E_TIMEOUT`	Upłynął limit czasu funkcji.

Uwagi

Ta funkcja blokuje się w stanie Alertable. Po pomyślnym wywołaniu urządzenia w zestawie urządzeń wirtualnych mogą zostać otwarte.

ClientVirtualDeviceSet::OpenDevice

Cel

Ta funkcja otwiera jedno z urządzeń w zestawie urządzeń wirtualnych.

Składnia

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

Parametry

Argument/kłótnia	Wyjaśnienie
`name`	Spowoduje to zidentyfikowanie zestawu urządzeń wirtualnych.
`ppVirtualDevice`	Po pomyślnym zakończeniu działania funkcji zwracany jest wskaźnik do urządzenia wirtualnego. To urządzenie jest używane do `GetCommand` i `CompleteCommand`.

Zwracane wartości

Argument/kłótnia	Wyjaśnienie
`NOERROR`	Funkcja zakończyła się pomyślnie.
`VD_E_ABORT`	Zażądano przerwania.
`VD_E_OPEN`	Wszystkie urządzenia są otwarte.
`VD_E_PROTOCOL`	Zestaw nie jest w stanie inicjowania lub to konkretne urządzenie jest już otwarte.
`VD_E_INVALID`	Nazwa urządzenia jest nieprawidłowa. Nie jest to jedna z nazw wchodzących w skład zestawu.

Uwagi

VD_E_OPEN można zwrócić bez problemu. Klient może wywołać OpenDevice za pomocą pętli, dopóki ten kod nie zostanie zwrócony. Jeśli skonfigurowano więcej niż jedno urządzenie, na przykład urządzenia i, zestaw wirtualnych urządzeń zwraca i unikatowe interfejsy urządzeń.

Funkcja GetConfiguration może służyć do oczekiwania na otwarcie urządzeń.

Jeśli ta funkcja nie powiedzie się, zostanie zwrócona wartość null za pośrednictwem ppVirtualDevice.

ClientVirtualDevice::GetCommand

Cel

Ta funkcja służy do uzyskiwania następnego polecenia w kolejce do urządzenia. Po zażądaniu ta funkcja czeka na następne polecenie.

Składnia

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

Parametry

Argument/kłótnia	Wyjaśnienie
`timeout`	Jest to czas oczekiwania w milisekundach. Użyj `INFINITE` lub wartości ujemnej, aby czekać bez końca. Użyj `0`, żeby sprawdzić polecenie. `VD_E_TIMEOUT` jest zwracana, jeśli polecenie nie jest obecnie dostępne. Jeśli wystąpi przekroczenie limitu czasu, klient zdecyduje o następnym działaniu.
`ppCmd`	Gdy polecenie zostanie pomyślnie zwrócone, parametr zwraca adres polecenia do wykonania. Zwracana pamięć jest tylko do odczytu. Po zakończeniu wykonywania polecenia ten wskaźnik jest przekazywany do procedury `CompleteCommand`.

Zwracane wartości

Argument/kłótnia	Wyjaśnienie
`NOERROR`	Pobrano polecenie.
`VD_E_CLOSE`	Urządzenie zostało zamknięte przez serwer.
`VD_E_TIMEOUT`	Polecenie nie było dostępne i upłynął limit czasu.
`VD_E_ABORT`	Klient lub serwer użył `SignalAbort`, aby wymusić zamknięcie.

Uwagi

Kiedy VD_E_CLOSE jest zwracany, SQL Server zamyka urządzenie. Jest to część normalnego zamknięcia. Po zamknięciu wszystkich urządzeń klient wywołuje ClientVirtualDeviceSet::Close, aby zamknąć zestaw urządzeń wirtualnych. Kiedy ta procedura musi zablokować się, aby oczekiwać na polecenie, wątek pozostaje w stanie Alertable.

ClientVirtualDevice::CompleteCommand

Cel

Ta funkcja służy do powiadamiania SQL Server o zakończeniu polecenia. Informacje dotyczące uzupełniania odpowiednie dla polecenia powinny zostać zwrócone.

Składnia

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

Parametry

Argument/kłótnia	Wyjaśnienie
`pCmd`	Jest to adres komendy poprzednio zwróconej z `ClientVirtualDevice::GetCommand`.
`completionCode`	Jest to kod stanu wskazujący stan ukończenia. Ten parametr musi zostać zwrócony dla wszystkich poleceń. Zwrócony kod powinien być odpowiedni dla wykonywanego polecenia. `ERROR_SUCCESS` jest używany we wszystkich przypadkach, aby oznaczyć pomyślnie wykonane polecenie. Aby uzyskać pełną listę możliwych kodów, zobacz plik `vdierror.h`.
`bytesTransferred`	Jest to liczba pomyślnie przeniesionych bajtów. Jest to zwracane tylko w przypadku poleceń transferu danych `Read` i `Write`.
`position`	Jest to odpowiedź tylko na polecenie `GetPosition`.

Zwracane wartości

Argument/kłótnia	Wyjaśnienie
`NOERROR`	Ukończenie zostało poprawnie zanotowane.
`VD_E_INVALID`	`pCmd` nie stanowił aktywnego polecenia.
`VD_E_ABORT`	`Abort` został zasygnalizowany.
`VD_E_PROTOCOL`	Urządzenie nie jest otwarte.

Uwagi

Żaden

ClientVirtualDeviceSet::SignalAbort

Cel

Ta funkcja służy do sygnalizowania, że powinno wystąpić nieprawidłowe zakończenie.

Składnia

int ClientVirtualDeviceSet::SignalAbort ();

Parametry

Argument/kłótnia	Wyjaśnienie
Żaden	Nie dotyczy

Zwracane wartości

Argument/kłótnia	Wyjaśnienie
`NOERROR`	Powiadomienie o `Abort` zostało pomyślnie opublikowane.

Uwagi

W dowolnym momencie klient może wybrać przerwanie operacji BACKUP lub RESTORE. Ta rutyna sygnalizuje, że wszystkie operacje powinny zostać przerwane. Stan ogólnego zestawu urządzeń wirtualnych wchodzi w stan Abnormally Terminated. Na żadnym urządzeniu nie są zwracane dalsze polecenia. Wszystkie nieuzupełniane polecenia są automatycznie wykonywane, zwracając ERROR_OPERATION_ABORTED jako kod ukończenia. Klient powinien wywołać ClientVirtualDeviceSet::Close po bezpiecznym zakończeniu użycia wszelkich bufory dostarczone klientowi.

ClientVirtualDeviceSet::Close

Cel

Ta funkcja zamyka zestaw urządzeń wirtualnych utworzony przez ClientVirtualDeviceSet::Create. Powoduje to zwolnienie wszystkich zasobów skojarzonych z zestawem wirtualnych urządzeń.

Składnia

int ClientVirtualDeviceSet::Close ();

Parametry

Argument/kłótnia	Wyjaśnienie
Żaden	Nie dotyczy

Zwracane wartości

Argument/kłótnia	Wyjaśnienie
`NOERROR`	Jest to zwracane po pomyślnym zamknięciu zestawu urządzeń wirtualnych.
`VD_E_PROTOCOL`	Nie podjęto żadnej akcji, ponieważ zestaw urządzeń wirtualnych nie został otwarty.
`VD_E_OPEN`	Urządzenia były nadal otwarte.

Uwagi

Wywołanie Close jest deklaracją klienta, że należy zwolnić wszystkie zasoby używane przez zestaw urządzeń wirtualnych. Klient musi upewnić się, że wszystkie swoje działania obejmujące bufory danych i urządzenia wirtualne są zakończone przed wywołaniem Close. Wszystkie interfejsy urządzeń wirtualnych zwrócone przez OpenDevice zostają unieważnione przez Close.

Klient może wydać wywołanie Create na interfejsie wirtualnego zestawu urządzeń po zwróceniu wywołania Close. Takie wywołanie spowodowałoby utworzenie nowego zestawu urządzeń wirtualnych dla kolejnej operacji BACKUP lub RESTORE.

Jeśli Close jest wywołane, gdy co najmniej jedno urządzenie wirtualne jest nadal otwarte, zostanie zwrócona VD_E_OPEN. W tym przypadku SignalAbort jest wyzwalane wewnętrznie, aby w miarę możliwości zapewnić odpowiednie wyłączenie. Zasoby VDI zostały zwolnione. Użytkownik powinien poczekać na wskazanie VD_E_CLOSE na każdym urządzeniu przed wywołaniem ClientVirtualDeviceSet::Close. Jeśli klient wie, że zestaw urządzeń wirtualnych jest już w stanie Abnormally Terminated, nie powinien oczekiwać wskazania VD_E_CLOSE z GetCommand, a może wywołać ClientVirtualDeviceSet::Close zaraz po zakończeniu aktywności na udostępnionych buforach.

ClientVirtualDeviceSet::OpenInSecondary

Cel

Ta funkcja otwiera zestaw urządzeń wirtualnych w kliencie drugorzędnym. Klient podstawowy musi już używać Create i GetConfiguration do konfigurowania zestawu urządzeń wirtualnych.

Składnia

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

Parametry

Argument/kłótnia	Wyjaśnienie
`setName`	To identyfikuje zestaw. Ta nazwa uwzględnia wielkość liter i musi być zgodna z nazwą używaną przez klienta głównego, kiedy ją wywołał `ClientVirtualDeviceSet::Create`.

Zwracane wartości

Argument/kłótnia	Wyjaśnienie
`NOERROR`	Funkcja zakończyła się pomyślnie.
`VD_E_PROTOCOL`	Zestaw urządzeń wirtualnych nie został utworzony, został już otwarty na tym kliencie lub zestaw urządzeń wirtualnych nie jest gotowy do akceptowania otwartych żądań od klientów pomocniczych.
`VD_E_ABORT`	Operacja jest przerywana.

uwagi Podczas korzystania z wielu modeli procesów klient podstawowy jest odpowiedzialny za wykrywanie normalnego i nietypowego zakończenia pomocniczych klientów.

ClientVirtualDeviceSet::GetBufferHandle

Cel

Niektóre aplikacje mogą wymagać więcej niż jednego procesu do działania na buforach zwracanych przez ClientVirtualDevice::GetCommand. W takich przypadkach proces odbierający polecenie może użyć GetBufferHandle, aby uzyskać uchwyt niezależny od procesu, który identyfikuje bufor. Ten uchwyt można następnie przekazać do dowolnego innego procesu, który również ma otwarty ten sam zestaw wirtualnych urządzeń. Następnie ten proces użyje ClientVirtualDeviceSet::MapBufferHandle, aby uzyskać adres buforu. Adres najprawdopodobniej będzie inny niż w jego partnerze, ponieważ każdy proces może mapować bufory pod różnymi adresami.

Składnia

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

Parametry

Argument/kłótnia	Wyjaśnienie
`pBuffer`	Jest to adres buforu uzyskanego z polecenia `Read` lub `Write`.
`BufferHandle`	Zwracany jest unikatowy identyfikator buforu.

Zwracane wartości

Argument/kłótnia	Wyjaśnienie
`NOERROR`	Funkcja zakończyła się pomyślnie.
`VD_E_PROTOCOL`	Zestaw urządzeń wirtualnych nie jest obecnie otwarty.
`VD_E_INVALID`	`pBuffer` nie jest prawidłowym adresem.

Uwagi

Proces, który wywołuje funkcję GetBufferHandle, jest odpowiedzialny za wywoływanie ClientVirtualDevice::CompleteCommand po zakończeniu transferu danych.

ClientVirtualDeviceSet::MapBufferHandle

Cel

Ta funkcja służy do uzyskania prawidłowego adresu bufora z uchwytu bufora uzyskanego z innego procesu.

Składnia

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

Parametry

Argument/kłótnia	Wyjaśnienie
`dwBuffer`	To jest uchwyt zwrócony przez `ClientVirtualDeviceSet::GetBufferHandle`.
`ppBuffer`	Jest to adres buforu, który jest prawidłowy w bieżącym procesie.

Zwracane wartości

Argument/kłótnia	Wyjaśnienie
`NOERROR`	Funkcja zakończyła się pomyślnie.
`VD_E_PROTOCOL`	Zestaw urządzeń wirtualnych nie jest obecnie otwarty.
`VD_E_INVALID`	`ppBuffer` jest nieprawidłowym uchwytem.

Uwagi

Zadbaj o poprawne przekazywanie uchwytów. Uchwyty są ograniczone do jednego zestawu urządzeń wirtualnych. Partnerzy przetwarzający muszą upewnić się, że dojścia buforu są używane tylko w ramach zestawu urządzeń wirtualnych, z którego pierwotnie uzyskano bufor.

Opinia

Czy ta strona była pomocna?

Last updated on 2026-04-13

specyfikacja zestawu SDK klienta SQL Server on Linux VDI

Konfiguracja uprawnień użytkownika

Funkcje klienta

ClientVirtualDeviceSet::Create

Cel

Składnia

Parametry

Zwracane wartości

Uwagi

ClientVirtualDeviceSet::GetConfiguration

Cel

Składnia

Parametry

Zwracane wartości

Uwagi

ClientVirtualDeviceSet::OpenDevice

Cel

Składnia

Parametry

Zwracane wartości

Uwagi

ClientVirtualDevice::GetCommand

Cel

Składnia

Parametry

Zwracane wartości

Uwagi

ClientVirtualDevice::CompleteCommand

Cel

Składnia

Parametry

Zwracane wartości

Uwagi

ClientVirtualDeviceSet::SignalAbort

Cel

Składnia

Parametry

Zwracane wartości

Uwagi

ClientVirtualDeviceSet::Close

Cel

Składnia

Parametry

Zwracane wartości

Uwagi

ClientVirtualDeviceSet::OpenInSecondary

Cel

Składnia

Parametry

Zwracane wartości

ClientVirtualDeviceSet::GetBufferHandle

Cel

Składnia

Parametry

Zwracane wartości

Uwagi

ClientVirtualDeviceSet::MapBufferHandle

Cel

Składnia

Parametry

Zwracane wartości

Uwagi

Opinia

Dodatkowe zasoby