Наборы API Windows

Внимание

Сведения в этом разделе относятся ко всем версиям Windows 10 и более поздним версиям. Здесь мы будем называть эти версии "Windows", указывая исключения там, где это необходимо.

Все версии Windows используют общую базу компонентов операционной системы (ОС), которые называют основной ОС (в некоторых контекстах эта общая база также называется OneCore). В основных компонентах ОС API Win32 организованы в функциональные группы, называемые наборами API.

Назначение набора API заключается в том, чтобы обеспечить разделение архитектуры между библиотекой DLL узла, в которой реализован заданный API Win32, и функциональный контракт, к которому принадлежит API. Разделение наборов API, предоставляемых между реализацией и контрактами, предлагает множество инженерных преимуществ для разработчиков. В частности, использование наборов API в коде может улучшить совместимость с устройствами Windows.

Наборы API предназначены специально для следующих сценариев:

  • Хотя на ПК поддерживается весь API Win32, на других устройствах Windows, таких как HoloLens, Xbox и другие, доступно только подмножество API Win32. Имя набора API дает вам стабильную вещь, о которую следует спрашивать, чтобы приложение может обнаруживать во время выполнения, доступна ли возможность на текущем устройстве. Сам запрос выполняется функцией IsApiSetImplemented .

  • Некоторые реализации API Win32 существуют в библиотеках DLL с разными именами на разных устройствах Windows. Использование имен наборов API вместо имен DLL-библиотек при определении доступности API и отложенной загрузке API обеспечивает правильный путь к реализации независимо от того, где именно реализован API.

Дополнительные сведения см. в статье об операции загрузчика набора API и обнаружении доступности набора API.

Совпадают ли наборы API и библиотеки DLL?

Нет— имя набора API определяет контракт, а не файл. Во время выполнения загрузчик сопоставляет этот контракт с помощью схемы набора API на текущем устройстве и перенаправляет ссылку на библиотеку DLL, содержащую реализацию. Это приём сокрытия реализации, при котором вам как вызывающей стороне не нужно точно знать, в каком именно модуле находится эта информация.

Этот метод позволяет рефакторингу модулей (разделить друг от друга, объединить, переименовать и т. д.) в разных версиях и выпусках Windows. И ваши приложения по-прежнему ссылаются и по-прежнему направляются к правильному коду во время выполнения.

Так почему наборы API имеют .dll в именах? Причина заключается в том, как реализуется загрузчик DLL. Загрузчик — это часть ОС, которая загружает библиотеки DLL и/или разрешает ссылки на DLL и определяет, что загружать, по имени модуля, записанному так же, как имена файлов в таблице импорта. Имена наборов API следуют тому же соглашению об именовании, чтобы их можно было размещать в одном и том же месте.

Загрузчик распознает имя, которое начинается с api- или ext- направляет его в среду выполнения набора API, расширение загрузчика, разрешающего контракты через схему. С этого момента имя анализируется правилами именования api, а не как именем файла, поэтому .dll суффикс не является частью разрешения имени контракта.

Вы можете передать имя набора API в LoadLibrary или использовать его в качестве целевого объекта задержки загрузки. Операция выполняется успешно, когда схема на текущем устройстве сопоставляет этот контракт с доступным хостом; на ПК необязательно существует фактический файл с таким именем где-либо. Если библиотека не сопоставлена с текущим устройством, прямой вызов LoadLibrary завершается ошибкой. Ссылка с отложенной загрузкой ведёт себя иначе: процесс всё равно запускается, а её отсутствие проявляется позже, когда вызывается API.

В любом случае успешная ссылка или загрузка не является само по себе свидетельством того, что реализация присутствует. Чтобы определить это, ознакомьтесь с разделом "Обнаружение доступности набора API".

Связывание зонтичных библиотек

Чтобы упростить ограничение кода на API Win32, поддерживаемые в основной ОС, мы предоставляем ряд зонтичных библиотек. Зонтичная библиотека позволяет подключить одну библиотеку вместо того, чтобы определять отдельную библиотеку импорта для каждого API, который вы вызываете.

Дополнительные сведения и информацию о том, как выбрать зонтичную библиотеку, соответствующую вашей цели, см. в статье Зонтичные библиотеки Windows.

Имена контрактов API-набора

Наборы API определяются именем контракта, который соответствует соглашениям, распознаваемым загрузчиком библиотеки.

Все названия контрактов следуют следующим соглашениям:

  • Имя начинается либо со строки api-, либо с ext-.
  • Текст имени может быть буквенно-цифровыми символами или дефисами (-). Тильда (~) отображается только в качестве разделителя перед именем группы.
  • Имя нечувствительно к регистру.

Используются две формы имени контракта, и вы можете столкнуться с одним из них.

Версионированное имя контракта заканчивается последовательностью l<n>->n>-<n<, где n состоит из десятичных цифр, например, ext-ms-win-core-samplefeature-l1-1-0. Конечные номера определяют одну конкретную версию контракта, а имя в этой форме должно считаться неизменяемым идентификатором для этой версии.

Псевдоним контракта не имеет никакой версии, напримерapi-win-core-samplefeature. Он определяет сам контракт, а не одну версию. Когда контракт организует свои отдельно доступные возможности в именованные группы, к группе обращаются, добавляя имя группы к псевдониму контракта, отделяя их тильдой: api-win-core-samplefeature~AdvancedOperations

Именаsamplefeature, используемые здесь, являются иллюстрированными именами для вымышленного компонента Windows.

Префиксы api- и ext-

Префикс — это соглашение об именовании. Изначально это было задумано, чтобы разграничить контракты, присутствующие в каждом соответствующем выпуске (api-), и контракты, которые могут отсутствовать (ext-). Это различие не было последовательно применено, и роль контракта может измениться с течением времени без переименования контракта.

Загрузчик не назначает значение префикса; он разрешает имена API иext- по тем же правилам. Не выводите доступность из префикса. Вместо этого выполните запрос — см. раздел Проверка доступности набора API.

Использование имени контракта

Два разных типа операции принимают имя контракта.

Операции загрузчика (например , LoadLibrary или P/Invoke) принимают имя контракта в том же месте, где обычно отображается имя модуля DLL. Добавление .dll в конце является общепринятым в этом контексте, но оно не требуется для разрешения имен наборов API и не является частью имени контракта. Используйте имя контракта вместо имени физического модуля DLL, чтобы обеспечить правильный маршрут к реализации независимо от того, где API фактически реализован на текущем устройстве. На диске не обязательно должен быть файл с таким названием контракта.

Примеры запросов проверки доступности обычно опускают суффикс .dll и используют форму, соответствующую тому, как адресуется API:

Поверхность API Форма запроса Example
Именованная группа <contract>~<group> api-win-core-samplefeature~AdvancedOperations
Группа по умолчанию Псевдоним контракта, без ~Default api-win-core-samplefeature
Версионированный контракт Полное название контракта с указанием версии ext-ms-win-core-samplefeature-l1-1-0

Имя группы нельзя сочетать с именем версионированного контракта.

Определение наборов API для API Win32

Чтобы определить, принадлежит ли определенный API Win32 набору API, просмотрите таблицу требований в справочной документации по API. Если API принадлежит набору API, таблица требований в статье содержит имя набора API и версию Windows, в которой API впервые появился в наборе API. Примеры API, принадлежащие набору API, см. в следующих статьях:

Если в заголовочном файле API есть вспомогательная функция Is<APIName>Present, используйте именно её при проверке доступности. Он уже содержит правильное имя набора API или группы, к которой относится API. Дополнительные сведения см. в разделе "Обнаружение доступности набора API".

В этом разделе

  • Last updated on