Win32 API
Wykorzystanie dokumentacji MSDN

Wprowadzenie

Uwagi

Dostępne rodzaje dokumentacji

Biblioteka MSDN zawiera kilka różnych rodzajów dokumentacji, których można użyć do implementacji funkcji.

• Omówienie tematów Są to ogólne omówienia tematów, które mają zapewnić ogólne zrozumienie interfejsu API. Te przeglądy często przedstawiają również najlepsze praktyki i strategie wdrażania.
• Próbki Pokazują użycie określonych interfejsów API. Są one na ogół bardzo uproszczone, niekoniecznie sprawdzają błędy i zazwyczaj nie używają frameworków takich jak MFC lub ATL. Stanowią punkt wyjścia do korzystania z funkcji.
• Odwołaj się do szczegółów wszystkich elementów każdego interfejsu API. Obejmuje to stałe / wyliczenia, interfejsy, funkcje i klasy.

Uwaga: wielu pracowników Microsoftu prowadzi blogi, na przykład The Old New Thing Raymonda Chena, które mogą uzupełniać dokumentację, ale blogi te nie zastępują dokumentacji.

Znajdowanie dokumentacji dla funkcji

Znalezienie dokumentacji dla funkcji jest często tak proste, jak wyszukiwanie przy użyciu dobrej wyszukiwarki. Jeśli to się nie powiedzie lub jeśli nie masz pewności co do określonych warunków, Indeks API systemu Windows może pomóc w zlokalizowaniu określonych funkcji. Dokumentację metod, interfejsów, wyliczeń i stałych można zwykle znaleźć, wyszukując nazwę za pomocą wyszukiwarki. Ponadto Centrum deweloperów systemu Windows może stanowić cenny punkt wyjścia.

Korzystanie z dokumentacji funkcji

Dokumentacja funkcji jest podzielona na kilka sekcji:

Przegląd

Opisuje, do czego służy ta funkcja. Ta sekcja pokaże również informacje o tym, czy funkcja jest przestarzała, czy może być niedostępna w przyszłych wersjach.

Składnia

Wyświetla deklarację funkcji z odpowiedniego nagłówka źródłowego. Jest to szybkie odniesienie do sygnatury funkcji.

Parametry

Objaśnia każdy z parametrów, niezależnie od tego, czy parametr jest wejściowy czy wyjściowy, oraz inne ważne uwagi.

Zwracana wartość

W tej sekcji wyjaśniono wyniki wywołania funkcji, w tym sposób wykrywania błędów i dostępne dodatkowe informacje. (Na przykład w tej sekcji zostanie wyraźnie określone, czy GetLastError dostarczy dodatkowe informacje dotyczące obsługi błędów).

Uwagi

Obejmuje wszelkie dodatkowe informacje wymagane do korzystania z funkcji, takie jak informacje o funkcjach pomocniczych, uzyskiwaniu odpowiednich uchwytów i usuwaniu zasobów.

Przykłady

Jeśli ta sekcja jest dostępna, zawiera przykład odpowiedniego zastosowania funkcji, która ma być punktem wyjścia do wdrożenia.

Wymagania

Podaje ważne informacje na temat warunków wstępnych wywołania funkcji. Informacje te obejmują:

• Minimalnie obsługiwany klient / serwer Pierwsza wersja systemu operacyjnego (obsługiwana przez Microsoft) w celu zapewnienia tej funkcji.
  _{(Uwaga: to pole jest myląco wprowadzane. Często funkcje są obsługiwane we wcześniejszej wersji systemu operacyjnego, ale w tym polu wyświetlana jest tylko najwcześniejsza wersja obsługiwana obecnie przez Microsoft . Na przykład funkcja CreateWindow jest obsługiwana od Windows 1.0 , ale dokumentacja pokazuje tylko, że jest obsługiwana od systemu Windows 2000. Internetowa wersja dokumentacji MSDN nie wskazuje, że jakakolwiek funkcja była obsługiwana w wersji systemu Windows wcześniejszej niż 2000, mimo że wiele z nich. należy zapoznać się ze starszą wersją dokumentacji zestawu SDK, na przykład dostarczoną na płycie CD MSDN. Lub po prostu zajrzyj do plików nagłówkowych).}
• Nagłówek Nagłówek SDK do #include który zawiera deklarację funkcji. Jeśli funkcja nie jest dostępna w nagłówku, wyświetli się informacja o procedurze wywołania funkcji (zwykle wywoływanie GetProcAddress celu wykonania dynamicznego łączenia w czasie wykonywania).
• Biblioteka Plik biblioteki przekazywany do konsolidatora w celu rozwiązania wyeksportowanych funkcji.
• DLL Plik (dostarczany z systemem operacyjnym), który zawiera wyeksportowaną funkcję.
• Koniec obsługi klienta / serwera Ostatnia wersja systemu Windows, która oficjalnie obsługuje interfejs API.
• Nazwy Unicode i ANSI W przypadku funkcji łańcuchowych, które mają zarówno warianty Unicode, jak i ANSI, wyszczególnia rzeczywiste wyeksportowane nazwy dwóch funkcji. Zwykle jest to tylko nazwa funkcji z przyrostkiem W lub A (odpowiednio).