Zestawy interfejsów API systemu Windows

Wszystkie wersje systemu Windows mają wspólną bazę składników systemu operacyjnego o nazwie core systemu operacyjnego (w niektórych kontekstach ta wspólna baza jest również nazywana OneCore). W podstawowych składnikach systemu operacyjnego interfejsy API win32 są zorganizowane w grupy funkcjonalne o nazwie zestawy interfejsów API .

Celem zestawu interfejsów API jest zapewnienie rozdzielenia architektury między biblioteką DLL hosta, w której zaimplementowano dany interfejs API Win32, a kontraktem funkcjonalnym, do którego należy interfejs API. Oddzielenie zestawów interfejsów API między implementacją a kontraktami zapewnia wiele korzyści inżynieryjnych dla deweloperów. W szczególności użycie zestawów interfejsów API w kodzie może poprawić zgodność z urządzeniami z systemem Windows.

Zestawy interfejsów API dotyczą w szczególności następujących scenariuszy:

• Chociaż pełny zakres interfejsu API Win32 jest obsługiwany na komputerach, tylko podzbiór interfejsu API Win32 jest dostępny na innych urządzeniach Windows, takich jak HoloLens, XBOX i inne urządzenia. Nazwa zestawu interfejsów API stanowi stabilny punkt odniesienia, dzięki czemu aplikacja może w czasie wykonywania wykryć, czy dana funkcja jest dostępna na danym urządzeniu. Samo zapytanie jest wykonywane przez funkcję IsApiSetImplemented .

• Niektóre implementacje interfejsu API Win32 istnieją w bibliotekach DLL o różnych nazwach na różnych urządzeniach z systemem Windows. Używanie nazw zestawów interfejsów API zamiast nazw bibliotek DLL podczas wykrywania dostępności interfejsu API i opóźniania ładowania interfejsów API zapewnia prawidłową trasę do implementacji niezależnie od tego, gdzie interfejs API jest rzeczywiście implementowany.

Aby uzyskać więcej informacji, zobacz operację modułu ładującego zestawów API i Wykrywanie dostępności zestawów API.

Czy zestawy interfejsów API i biblioteki DLL są takie same?

Nie — nazwa zestawu interfejsów API identyfikuje kontrakt, a nie plik. W czasie wykonywania program ładujący rozwiązuje ten kontrakt za pomocą schematu zestawów API na danym urządzeniu i kieruje odwołanie do biblioteki DLL, która zawiera implementację. Jest to technika ukrywania implementacji, w której użytkownik będący obiektem wywołującym nie musi wiedzieć dokładnie, który moduł hostuje informacje.

Metoda umożliwia refaktoryzację modułów (dzielenie, konsolidowanie, przemianowywanie i tak dalej) w różnych wersjach i edycjach systemu Windows. Aplikacje nadal pozostają połączone i nadal są kierowane do właściwego kodu w czasie działania.

Dlaczego więc zestawy interfejsów API mają .dll w nazwach? Przyczyną jest sposób implementacji modułu ładującego biblioteki DLL. Program ładujący jest częścią systemu operacyjnego, która ładuje biblioteki DLL i/lub rozwiązuje odwołania do bibliotek DLL oraz ustala, co należy załadować, na podstawie nazwy modułu zapisanej w tabeli importu w taki sam sposób, w jaki zapisuje się nazwy plików. Nazwy zestawów interfejsów API są zgodne z tą samą konwencją, aby mieściły się w tym samym miejscu.

Moduł ładujący rozpoznaje nazwę rozpoczynającą się od api- lub ext- i przekazuje ją do środowiska uruchomieniowego zestawu API, będącego rozszerzeniem modułu ładującego, które rozstrzyga kontrakty za pośrednictwem schematu. Od tego momentu nazwa jest interpretowana zgodnie z regułami nazewnictwa zestawów API, a nie jako nazwa pliku, więc sufiks .dll nie jest częścią nazwy kontraktu podlegającej rozstrzygnięciu.

Możesz przekazać nazwę zestawu API do LoadLibrary lub użyć jej jako celu ładowania opóźnionego. Operacja kończy się powodzeniem, gdy schemat na bieżącym urządzeniu mapuje ten kontrakt na hosta, którego można użyć; nie musi istnieć żaden rzeczywisty plik o tej nazwie nigdzie na komputerze. Jeśli umowa nie jest mapowana na bieżącym urządzeniu, bezpośrednie wywołanie LoadLibrary kończy się niepowodzeniem. Referencja ładowana z opóźnieniem działa inaczej: proces nadal się uruchamia, a brak ujawnia się dopiero później, gdy wywoływane jest API.

Tak czy inaczej, pomyślne łącze lub ładowanie nie jest same w sobie dowodem na to, że implementacja jest obecna. Aby to ustalić, zobacz Wykrywanie dostępności zestawu interfejsów API.

Łączenie bibliotek parasolowych

Aby ułatwić ograniczenie kodu do interfejsów API Win32 obsługiwanych w podstawowym systemie operacyjnym, udostępniamy szereg bibliotek parasolowych . Biblioteka parasolowa umożliwia łączenie pojedynczej biblioteki zamiast identyfikowania pojedynczej biblioteki importu dla każdego wywoływanego interfejsu API.

Aby uzyskać więcej informacji i wybrać bibliotekę parasolową zgodną z celami, zobacz Windows biblioteki parasolowe.

Nazwy kontraktów zestawu interfejsów API

Zestawy interfejsów API są identyfikowane przez nazwę kontraktu zgodną z konwencjami rozpoznawaną przez moduł ładujący biblioteki.

Wszystkie nazwy kontraktów mają następujące konwencje:

• Nazwa zaczyna się od ciągu api- lub od ciągu ext-.
• Treść nazwy może być znakami alfanumerycznymi lub kreskami (-). Tylda (~) jest wyświetlana tylko jako separator przed nazwą grupy.
• Nazwa jest niewrażliwa na wielkość liter.

Dwie formy nazwy kontraktu są używane i można napotkać jedną z nich.

Nazwa kontraktu w wersji kończy się sekwencją l-n-n,gdzie<>><><n składa się z cyfr dziesiętnych — na przykład . ext-ms-win-core-samplefeature-l1-1-0 Końcowe numery identyfikują jedną konkretną wersję kontraktu, a nazwa w tym formularzu powinna być traktowana jako niezmienny identyfikator tej wersji.

Alias umowy nie zawiera wersji — na przykład api-win-core-samplefeature. Identyfikuje sam kontrakt, a nie jedną wersję. Gdy kontrakt organizuje indywidualnie dostępne funkcje w nazwanych grupach, grupa jest adresowana przez dołączenie nazwy grupy do aliasu kontraktu oddzielonego tyldą: api-win-core-samplefeature~AdvancedOperations.

Nazwy samplefeature używane w tym miejscu to ilustracyjne nazwy fikcyjnego składnika Windows.

Prefiksy api- i ext-

Prefiks jest konwencją nazewnictwa. Pierwotnie miało to na celu odróżnienie kontraktów, które występują w każdej kwalifikującej się edycji (api-), od kontraktów, które mogą nie występować (ext-). To rozróżnienie nie było konsekwentnie stosowane, a rola kontraktu może ulec zmianie w czasie bez zmiany nazwy kontraktu.

Moduł ładujący nie nadaje prefiksowi żadnego znaczenia; interpretuje nazwy api- i ext- według tych samych zasad. Nie wywnioskuj dostępności z prefiksu. Zamiast tego wykonaj zapytanie — zobacz Wykrywanie dostępności zestawu interfejsów API.

Używanie nazwy kontraktu

Dwa różne rodzaje operacji przyjmują nazwę kontraktu.

Operacje modułu ładującego — takie jak LoadLibrary lub P/Invoke — przyjmują nazwę kontraktu w tym samym miejscu, w którym zwykle pojawia się nazwa modułu DLL. Dołączony element .dll jest w tym kontekście przyjętą konwencją, ale nie jest wymagany przez mechanizm rozpoznawania nazw zestawu interfejsów API i nie jest częścią nazwy kontraktu. Użyj nazwy kontraktu zamiast fizycznej nazwy modułu DLL, aby zapewnić poprawną trasę do implementacji niezależnie od tego, gdzie interfejs API jest rzeczywiście implementowany na bieżącym urządzeniu. Nie trzeba mieć pliku o tej nazwie kontraktu na dysku.

Przykłady zapytań o dostępność zwykle pomijają sufiks .dll i używają formy zgodnej ze sposobem, w jaki odwołuje się do interfejsu API:

Nie można połączyć nazwy grupy z wersjonowaną nazwą kontraktu.

Identyfikowanie zestawów API dla interfejsu API Win32

Aby określić, czy określony interfejs API Win32 należy do zestawu interfejsów API, zapoznaj się z tabelą wymagań w dokumentacji referencyjnej interfejsu API. Jeśli interfejs API należy do zestawu interfejsów API, tabela wymagań w artykule zawiera listę nazwy zestawu interfejsów API i wersji systemu Windows, w której interfejs API został po raz pierwszy wprowadzony do zestawu interfejsów API. Przykłady interfejsów API należących do zestawu interfejsów API można znaleźć w następujących artykułach:

• AllowSetForegroundWindow
• FindWindowEx
• GetClassFile

Jeśli nagłówek interfejsu API udostępnia funkcję pomocniczą Is<APIName>Present, używaj jej podczas sprawdzania dostępności. Zawiera już poprawną nazwę zestawu API lub grupy zawierającej ten interfejs API. Aby uzyskać więcej informacji, zobacz Wykrywanie dostępności zestawu interfejsów API.

W tej sekcji

• operacja programu ładującego zestawów API
• Wykryj dostępność zestawu interfejsów API
• biblioteki parasolowe systemu Windows