НТВ плюс 

Описание API. Чем API Google Календаря отличается от API любого другого удалённого сервера в сети? Open API стратегия

  • Tutorial

Удобство работы с любым API во многом зависит от того, как написана и оформлена его документация. Cейчас мы ведём работу по стандартизации и унификации описания всех наших API, и вопросы документирования для нас особенно актуальны.
После долгих поисков мы решили оформлять документацию в формате RAML . Так называется специализированный язык для описания REST API. О его возможностях и преимуществах мы расскажем в этой статье.

Почему RAML

Как нужно документировать API? Вопрос этот не так прост, как может показаться на первый взгляд.
Первый и самый простой вариант, который приходит на ум — представить описание к API в виде обычного текстового документа. Так делают очень многие (в том числе и очень известные компании). Мы тоже не раз пользовались этим способом. При всей своей простоте он обладает следующими недостатками:
  • текстовую документацию сложно поддерживать в актуальном состоянии;
  • зачастую словесные описания API оказываются недостаточно наглядными;
  • сфера использования «словесной» документации очень ограничена (например, на её основе нельзя сгенерировать интерактивную тестовую страницу).
Чтобы упростить процесс документирования, можно использовать специализированные инструменты и сервисы. Как правило, они генерируют документацию на основе описания в некотором стандартизованном формате — обычно это JSON или Markdown.

Ни один из этих форматов для написания документации не подходит. JSОN был изначально создан для обмена данными в вебе. При использовании его для других целей поневоле приходится прибегать к помощи «костылей» — например, кастомных полей, начинающихся со знака $. Кроме того, составлять описания в формате JSON вручную — дело достаточно рутинное и утомительное (в особенности если речь идёт об описаниях большого размера).

На описанные выше трудности обращали внимание многие пользователи популярного инструмента Swagger . Вскоре разработчики Swagger решили упростить работу по написанию спецификаций и создали фирменный редактор с поддержкой формата YAML.

Конечно, YAML гораздо удобнее, чем JSON. Но и его использование сопряжено с определёнными трудностями. Дело в том, что в описаниях API всегда имеются повторяющиеся элементы (например, схема ответа, которая может быть одинаковой для разных типов HTTP-запросов), которые приходится всякий раз прописывать вручную. Вот если бы можно их было раз и навсегда прописать в отдельном файле и ссылаться на него в случае небходимости… Но, увы, пока что такой возможности нет.

Что касается формата Markdown (он используется, например, в API BluePrint), то предназначен в первую очередь для оформления текста, а не для использования в качестве основы для генерирования. Приспособить его под документирование API очень сложно. По этой же причине не привели к каким-либо заметным результатам попытки cоздать формат описания API на базе XML — например, язык WADL (Web Application Desription Language), разработанный компанией Sun Microsystems ещё в 2009 году, но так и не получивший широкого распространения.

Создатели проекта RAML (эта аббревиатура означает RESTful API Modeling Language — язык для моделирования REST API) предприняли попытку разработать язык, предназначенный исключительно для описания API и исправить недочёты, свойственные другим форматам. Первая версия спецификации RAML была опубликована в 2013 году. Основным разработчиком RAML является компания MuleSoft; в проекте также принимают участие представители таких известных компаний, как Cisco, PayPal, ВoxInc. и других.

Несомненными преимуществами RAML являются:

  • простой и логичный синтаксис, основанный на формате YAML;
  • поддержка наследования и возможность подключения внешних файлов спецификаций.
Дополнительным плюсом является наличие большого количества конвертеров, парсеров и генераторов интерактивной документации. О некоторых из них мы расскажем ниже, а пока перейдём к обзору особенностей синтаксиса RAML.

Краткое введение в RAML

Структура документа

Файл спецификаций на RAML состоит из следующих структурных элементов:
  • вводная часть («шапка»);
  • схема безопасности;
  • описание профилей;
  • описание объектов и методов;
  • описание ответов.
Рассмотрим эти элементы подробнее.

Вводная часть

Каждый документ на RAML начинается с вводной части, которая включает четыре обязательных элемента:
  • версия RAML;
  • имя документа;
  • URI, по которому доступен API;
  • версия API, описываемая в документации.
Выглядит это так:

#% RAML 0.8 title: Example API baseUri: http://api.example.com/{version} version: v1
Вводная часть может также включать различную дополнительную информацию — например, сведения об используемом протоколе для связи с API:

Protocols:
Можно во вводной части прописать и метаданные файла документации:

Documentation - title: Home content: | API Test Documentation

Схемы безопасности

Чтобы начать работать с любым API, нужно пройти процедуру авторизации. Она может осуществляться разными способами: через OAuth, с помощью токенов, либо посредством простой HTTP-аутентификации. Для описания этой процедуры в RAML используются схемы безопасности (security schemes).
Рассмотрим в качестве примера, как описывается авторизация с использованием протокола OAuth2:
#%RAML 0.8 title: Example API version: 1 baseUri: https://api.example.com/{version} securedBy: securitySchemes: - oauth_2_0: type: OAuth 2.0 describedBy: headers: Authorization: type: string queryParameters: access_token: type: string responses: 401: description: | Bad or expired token. 403: description: | Bad OAuth request settings: authorizationUri: https://example.com/oauth/authorize accessTokenUri: https://example.com/oauth/token authorizationGrants: [ code, token ]
Приведённый фрагмент содержит следующую информацию:
  • в параметре type указывается, что в API используется авторизация по протоколу OAuth2;
  • далее указывается, что авторизационные данные можно передавать либо в заголовке Authorization, либо в query-параметре access_token;
  • после этого следуют возможные коды ответов и их описания;
  • в конце раздела, в секции settings указываются URL для авторизации, URL для получения токена, а также необходимые для аутентификации параметры (authorization grants).
Для удобства схемы безопасности можно сохранять в отдельных файлах.raml или.yml, и затем обращаться к ним в случае необходимости:

#%RAML 0.8 title: Example API version: 1 baseUri: https://api.example.com/{version} securedBy: securitySchemes: - oauth_2_0: !include oauth_2_0.yml
Это помогает ускорить процесс документирования, избежать лишних повторений и сделать документацию менее громоздкой.

Объекты и методы

Далее перечисляются основные объекты и пути к ним, а также HTTP-методы, которые используются с этими объектами:

/document get: put: post: /{documentId} get: delete:
В приведённом примере описывается API, с помощью которого можно работать с документами. Мы можем скачивать документы на локальную машину (GET), изменять cуществующие документы (PUT) и загружать новые (POST). С каждым отдельным документом ({documentId}) мы можем также выполнять следующие операции: загрузка на локальную машину (GET) и удаление (DELETE).
HTTP-заголовки, используемые с тем или иным методом, описываются при помощи свойства headers, например:

/documents get headers: X-Auth-Token: required: true
Обратите внимание на свойство required: оно указывает, является ли заголовок обязательным (true) или необязательным (false).
В описании объектов и методов могут использоваться многочисленные дополнительные параметры. Рассмотрим следующий пример:

/document /{documentId} uriParameters: id: description: document identification number type: string pattern: ^{2}\-{3}\-\d{2}\-\d{5}$
Здесь мы указываем, что каждый из документов, доступ к которым можно получить через API, имеет собственный идентификационный код в виде строки (type: string), а также описываем формат этого кода с помощью регулярных выражений.

Свойства description, type и pattern можно использовать и в описаниях методов, например:
/documents get: description: Retrieve a list of documents post: description: Add a new document body: application/x-www-form-urlencoded formParameters: id: description: document identification number type: string pattern: {2}\-{3}\-\d{2}\-\d{5}$ name: description: the name of the document type: string required: true author: description: The name of the author type: string required: true
В описании метода POST мы указываем параметры, которые нужно передать в теле запроса для добавления нового документа: ID, имя и имя автора. Каждый из этих параметров является строкой (type: string). Обратите внимание на свойство required: оно указывает, является ли параметр обязательным (true) или необязательным (false).

Для каждого метода можно прописать индивидуальную схему безопасности:

/documents get

Query-параметры

Для каждого метода в документации можно указать query-параметры, которые будут использоваться в запросе. Для каждого query-параметра указываются следующие характеристики: имя, тип, описание и пример:

/document: get: queryParameters: author: displayName: Author type: string description: The author"s full name example: Ivan Petrov required: false name: displayName: Document Name type: string description: The name of the document example: Delivery contract required: false signingDate: displayName: signingDate type: date description: The date when the document was signed example: 2015-07-15 required: false

Профили

Чтобы избежать лишних повторений в описаниях, в RAML используются профили (traits), которые прописываются во вводной части документа:

#% RAML 0.8 title: Example API baseUri: http://api.example.com/{version} version: v1 traits: - searchable: queryParameters: author: displayName: Author type: string description: The author"s full name example: Ivan Petrov required: false name: displayName: Document Name type: string description: The name of the document example: Delivery contract required: false signingDate: displayName: signingDate type: date description: The date when the document was signed example: 2015-07-15 required: false
В дальнейшем к профилю можно обращаться при описании любых методов:

/document: get: is:
Более подробно о профилях и особенностях их использования можно почитать в официальной документации (раздел Traits).

Описание ответа

В описании ответа обязательно указывается его код. Также в описание можно добавить схему (schema) — перечисление входящих в ответ параметров и их типов. Можно также привести пример конкретного ответа (example).

/documents: /{documentId}: get: description: Retrieve document information responses: 200: body: application/json: schema | {"$schema": “http://json-schema.org/schema”, "type":"object" "description": "a document" "properties": { "id":{"type":"string"} "name":{"type":"string"} "author":{"type":"string"} "signingDate": {"type":"date"} example: | {"data:" { "id": "DOC3456" "name": "New Delivery Contract" "author": "Ivan Petrov" "signingDate": "2015-05-20" }, "success": true "status": 200 }
Cхемы ответов можно сохранять в отдельных файлах формата.yml или.raml и обращаться к ним в других частях документации:

Schemas: - !include document-schema.yaml /articles: get: responses: 200: body: application/json: schema: document

Визуализация и генерация документации

RAML2HTML и другие конвертеры

Несмотря на то, что RAML — формат относительно новый, для него уже разработано достаточное количество конвертеров и парсеров. В качестве примера можно привести ram2htmtl , генерирующий на основе описания в формате RAML статическую HTML-страницу.
Устанавливается он при помощи менеджера пакетов npm:

$ npm -i g raml2html
Чтобы сконвертировать RAML-файл в HTML, достаточно выполнить простую команду:
$ raml2html api.raml > index.html

Компания Mulesoft (один из активных участников проекта RAML) создала специальный онлайн-инструмент, с помощью которого можно упростить работу по написанию документации и последующему тестированию API. Называется он .
Чтобы начать им пользоваться, нужно сначала зарегистрироваться на сайте. После этого можно приступать к работе. API designer предоставляет, во-первых, удобный интерактивный редактор для написания документации онлайн, а во-вторых — платформу для тестирования.
Выглядит всё это так:

В правой части страницы автоматически генерируется интерактивная документация. Здесь же можно и протестировать API: для этого достаточно просто развернуть описание нужного запроса и нажать на кнопку Try it.

API Designer позволяет также загружать RAML-файлы с локальной машины. Поддерживается импорт файлов описаний API для Swagger.
Кроме того, API Designer хранит статистику тестовыx запросов к API.

API console

API console — полезный инструмент, разработанный всё той же компанией MuleSoft. С его помощью можно прямо в браузере генерировать документацию к API. Файлы спецификаций можно как загрузить с локальной машины, так и указать ссылку на внешний

Министерство образования и науки РФ

Государственное образовательное учреждение

Высшего профессионального образования

«Ижевский государственный технический университет имени М.Т. Калашникова»

Кафедра «Вычислительная техника»

Пояснительная записка к курсовой работе

по дисциплине «Операционные системы»

Всплывающие подсказки

Выполнил: студент гр. 8-78-1

Саляхутдинов К.О.

Проверил:

преподаватель, к.т.н. Вахрушева Е.А.

Ижевск, 2014

Введение 3

Описание API-функций 4

Принцип работы 13

Листинг программы 14

Файл hint.inc 14

Файл hint.asm 15

Файл hint.rc 20

Демонстрация работы программы 22

Список литературы 23

Введение

В компьютерных интерфейсах подсказка (с англ. tooltip, hint) служит дополнительным средством обучения интерфейсу.

Типы подсказок:

    Всплывающая подсказка - появляется при подведении курсора к интересующему объекту или в случае недопустимого действия (например, ввода текста вместо числа). В случае редакторов с автодополнением всплывающие подсказки могут появляться при вводе названий функций и переменных, указывая их характеристики (тип, прототип, количество и тип аргументов и т. д.).

    Подсказка при запуске - появляющееся после запуска программы окно, демонстрирующее краткий текст по необычным/нестандартным возможностям программы. Обычно при каждом запуске текст меняется, позволяя пользователю изучать возможности программы «походя». В ряде случаев появление окна с текстом, требующим особых действий для закрытия, может расцениваться пользователями как раздражающее.

    Контекстная - в некоторых типах интерфейсов командной строки (например, в IOS) - появляющаяся при вводе команды и вопросительного знака. При этом введённый текст не исчезает, а подсказка появляется над введенным текстом, позволяя понять, что можно/следует вводить дальше.

В данной курсовой работе в качестве цели использовалось создание именно всплывающих подсказок, которые можно установить на любые объекты окна.

Описание api-функций

CreateDialogParam

Создает немодальное диалоговое окно из шаблона ресурса блока диалога. Перед показом диалогового окна на экране, функция отправляет в процедуру блока диалога определяемое программой значение сообщения WM_INITDIALOG, как параметр lParam. Прикладная программа может использовать это значение, чтобы инициализировать элементы управления диалогового окна.

Синтаксис:

HWND CreateDialogParam(

HINSTANCE hInstance, // дескриптор экземпляра программы

LPCTSTR lpTemplateName, // идентификация шаблона блока диалога

HWND hWndParent, // дескриптор окна владельца

DLGPROC lpDialogFunc, // указатель на процедуру диалогового окна

LPARAM dwInitParam // инициализационное значение

Параметры:

    hInstance - идентифицирует экземпляр модуля, исполняемый файл которого содержит шаблон диалогового окна.

    lpTemplateName - идентифицирует шаблон диалогового окна. Этот параметр - или указатель на строку символов с нуль-терминатором в конце, которая определяет имя шаблона диалогового окна, или целочисленное значение, которое определяет идентификатор ресурса шаблона блока диалога. Если параметр определяет идентификатор ресурса, его старшее слово должно быть нулевым, а младшее слово должно содержать идентификатор. Вы можете использовать макрокоманду MAKEINTRESOURCE, чтобы создать это значение.

    hWndParent - идентифицирует окно, которое владеет блоком диалога.

    lpDialogFunc - указывает на процедуру диалогового окна.

    dwInitParam - устанавливает значение, передаваемое процедуре диалогового окна в параметре lParam сообщения WM_INITDIALOG.

Возвращаемые значения: если функция завершилась успешно, возвращается значение дескриптор окна блока диалога. Если функция потерпела неудачу, возвращается значение ПУСТО (NULL).

SetFocus

Устанавливает фокус клавиатуры на заданном окне. Окно должно быть связано с очередью сообщений вызывающего потока.

Синтаксис:

HWND WINAPI SetFocus(

In_opt_ HWND hWnd //дескриптор окна

Параметры:

    hWnd - идентифицирует окно, которое примет ввод информации с клавиатуры. Если этот параметр - ПУСТО (NULL), нажатия клавиши игнорируются.

Возвращаемые значения: если функция завершается успешно, величина возвращаемого значения - дескриптор окна, которое до этого имело фокус клавиатуры. Если параметр hWnd недопустимый или окно не связано с очередью сообщений вызывающего потока, величина возвращаемого значения - ПУСТО (NULL).

Lstrcpy

Копирует строку в буфер.

Синтаксис:

LPTSTR WINAPI lstrcpy(

Out_ LPTSTR lpString1,

In_ LPTSTR lpString2

Параметры:

    lpString1 - указатель на буфер, который получает содержимое строки, указанное при помощи параметра lpString2. Буфер должен быть достаточно большим, чтобы принять строку, включая символ завершающего нуля.

    lpString2 - указатель на строку с завершающим нулем, которая копируется.

Возвращаемые значения: если функция завершается успешно, возвращаемое значение - указатель на буфер. Если функция завершается ошибкой, возвращаемое значение NULL.

DestroyWindow

Уничтожает определенное окно. Функция посылает сообщения WM_DESTROY и WM_NCDESTROY окну, чтобы дезактивировать его и удалить фокус клавиатуры из него. Функция также уничтожает меню окна, очищает очередь потоков сообщений, уничтожает таймеры, удаляет монопольное использование буфера обмена и разрывает цепочку просмотра окон буфера обмена (если окно имеет наверху цепочку просмотров).

Если окно - родитель или владелец окон, то DestroyWindow автоматически уничтожает связанные дочерние или находящиеся в собственности окна, когда она уничтожает окно владельца или родителя. Функция сначала уничтожает дочерние или находящиеся в собственности окна, и затем она уничтожает окно владельца или родителя. DestroyWindow также уничтожает немодальные диалоговые окна, созданные функцией CreateDialog.

Синтаксис:

BOOL WINAPI DestroyWindow(

In_ HWND hWnd //дескриптор окна

Параметры:

    hWnd - идентификатор окна, которое будет разрушено.

Возвращаемые значения: если функция завершается успешно, возвращаемое значение отлично от нуля. Если функция не выполняет задачу, возвращаемое значение нулевое.

Lstrlen

Возвращает длину указанной строки в байтах, не включая символ завершающего нуля.

Синтаксис:

int WINAPI lstrlen(

In_ LPCTSTR lpString

Параметры:

    lpString - указатель на строку с завершающим нулем.

Возвращаемые значения: возвращаемое значение указывает длину строки, в значениях TCHAR.

GetDlgItem

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

Синтаксис:

HWND WINAPI GetDlgItem(

In_opt_ HWND hDlg,

In_ int nIDDlgItem

Параметры:

    nIDDlgItem - устанавливает идентификатор извлекаемого органа управления.

Возвращаемые значения: если функция завершается успешно, возвращаемое значение - дескриптор окна указанного органа управления. Если функция завершается ошибкой, возвращаемое значение - ПУСТО (NULL), которое указывает на недопустимый дескриптор диалогового окна или несуществующий орган управления.

GetCursorPos

Извлекает позицию курсора, в экранных координатах.

Синтаксис:

BOOL WINAPI GetCursorPos(

Out_ LPPOINT lpPoint

Параметры:

    lpPoint - указатель на структуру POINT, которая получает экранные координаты курсора.

Возвращаемые значения:

TextOut

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

Синтаксис:

In_ int nXStart,

In_ int nYStart,

In_ LPCTSTR lpString,

In_ int cchString

Параметры:

    nXStart - устанавливает x-координату, в логических координатах, контрольной точки, которую система использует для выравнивания строки.

    nYStart - устанавливает y-координату, в логических координатах, контрольной точки, которую система использует для выравнивания строки.

    lpString - указатель на строку, которую нужно написать. Строка не должна завершаться нуль-терминатором, так как параметр cbString задает длину строки.

    cbString - устанавливает длину строки. Для функции ANSI, это количество BYTE (байтов), а для функции Unicode, это является количеством WORD (слов).

Возвращаемые значения: если функция завершается успешно, величина возвращаемого значения - не ноль. Если функция завершается с ошибкой, величина возвращаемого значения - ноль.

SetBkColor

Устанавливает текущий цвет фона в заданном коде цвета или в самом близком физическом цвете, если устройство не может предоставить указанный код цвета.

Синтаксис:

COLORREF SetBkColor(

In_ COLORREF crColor

Параметры:

    Hdc - дескриптор контекста устройства.

    crColor - определяет новый цвет фона. Чтобы создать значение COLORREF, используйте макрокоманду RGB.

Возвращаемые значения: если функция завершается успешно, возвращаемое значение определяет предыдущий цвет фона как значение COLORREF.

SetTextColor

Устанавливает цвет текста для заданного устройства в заданный цвет.

Синтаксис:

COLORREF SetTextColor(

In_ COLORREF crColor

Параметры:

    Hdc - дескриптор контекста устройства.

    crColor - устанавливает цвет текста.

Возвращаемые значения: если функция завершается успешно, возвращаемое значение - ссылка на цвет предыдущего цвета текста как значение COLORREF.

BeginPaint

Готовит заданное окно к окрашиванию и заполняет структуру PAINT-STRUCT информацией об окрашивании.

Синтаксис:

Out_ LPPAINTSTRUCT lpPaint

Параметры:

    hwnd - дескриптор окна, которое будет перекрашено.

    lpPaint - указатель на структуру PAINTSTRUCT, которая получит информацию об окрашивании.

Возвращаемые значения: если функция завершается успешно, возвращаемое значение - дескриптор контекста устройства отображения для заданного окна. Если функция завершается ошибкой, возвращаемое значение - NULL, которое указывает, что никакой контекст устройства (DC) отображения не доступен.

EndPaint

Отмечает конец окрашивания в заданном окне. Эта функция требуется для каждого вызова в функции BeginPaint, но только после того, как окрашивание завершается полностью.

Синтаксис:

In_ const PAINTSTRUCT *lpPaint

Параметры:

    hWnd - дескриптор окна, которое было перекрашено.

    lpPaint - указатель на структуру PAINTSTRUCT, которая содержит информацию об окрашивании, извлекаемую при помощи функции BeginPaint.

Возвращаемые значения: возвращаемое значение всегда не нуль.

GetTextExtentPoint 32

Вычисляет ширину и высоту заданной строки текста.

Синтаксис:

BOOL GetTextExtentPoint32(

In_ LPCTSTR lpString,

In_ int cbString,

Out_ LPSIZE lpSize

Параметры:

    Hdc - дескриптор контекста устройства.

    lpString - указатель на буфер, который задает текстовую строку. Строка не должна быть закончена нулем, потому что параметр cbString устанавливает длину строки.

    cbString - устанавливает длину буфера lpString.

    lpSize - указатель на структуру SIZE, которая принимает размеры строки, в логических единицах измерения.

Возвращаемые значения: если функция завершается успешно, возвращаемое значение не нуль. Если функция завершается с ошибкой, величина возвращаемого значения - ноль.

MoveWindow

Изменяет позицию и габариты определяемого окна. Для окна верхнего уровня, позиция и габариты отсчитываются относительно левого верхнего угла экрана. Для дочернего окна - относительно левого верхнего угла рабочей области родительского окна.

Синтаксис:

BOOL WINAPI MoveWindow(

In_ int nWidth,

In_ int nHeight,

In_ BOOL bRepaint

Параметры:

    hWnd - дескриптор окна.

    X - устанавливает новую позицию левой стороны окна.

    Y - устанавливает новую позицию верхней части окна.

    nWidth - устанавливает новую ширину окна.

    nHeight - устанавливает новую высоту окна.

    bRepaint - определяет, должно ли окно быть перерисовано. Если этот параметр - ИСТИНА (TRUE), окно принимает сообщение WM_PAINT. Если параметр – ЛОЖЬ (FALSE), никакого перекрашивания какого-либо сорта не происходит. Это применяется к рабочей области, нерабочей области (включая область заголовка и линейки прокрутки) и любой части родительского окна, раскрытого в результате перемещения дочернего окна.

Возвращаемые значения: если функция завершилась успешно, возвращается значение не нуль. Если функция потерпела неудачу, возвращаемое значение - ноль.

GetWindowRect

Извлекает размеры рамки ограничивающей прямоугольник заданного окна. Размеры даются в экранных координатах, которые отсчитываются относительно левого верхнего угла экрана.

Синтаксис:

BOOL WINAPI GetWindowRect(

Out_ LPRECT lpRect

Параметры:

    hWnd - дескриптор окна.

    lpRect - указатель на структуру, которая принимает экранные координаты левого верхнего и нижнего правого углов окна.

Возвращаемые значения: если функция завершилась успешно, возвращается значение - не нуль. Если функция потерпела неудачу, возвращаемое значение - ноль.

ReleaseDC

Освобождает контекст устройства (DC) для использования другими приложениями. Действие функции ReleaseDC зависит от типа контекста устройства (DC). Она освобождает только общий и контекст устройства (DC) окна. Не имеет никакого действия на контексты устройства класса или частный DC.

Синтаксис:

Параметры:

    hWnd - дескриптор окна, контекст устройства (DC) которого должен быть освобожден.

    hDC - дескриптор контекста устройства (DC), который будет освобожден.

Возвращаемые значения: возвращаемое значение указывает, был ли контекст устройства (DC) освобожден. Если контекст устройства был освобожден, возвращаемое значение равно 1. Если контекст устройства (DC) не был освобожден, величина возвращаемого значения - ноль.

GetDC

Извлекает дескриптор дисплейного контекста устройства (DC) для рабочей области заданного окна или для всего экрана. Вы можете использовать возвращенный дескриптор в последующих функциях GDI, чтобы рисовать в контексте устройства.

Синтаксис:

Параметры:

    hWnd - дескриптор окна, контекст устройства (DC) которого должен извлечься.

Возвращаемые значения: если функция завершается успешно, возвращаемое значение - дескриптор контекста устройства (DC) для рабочей области заданного окна. Если функция завершается ошибкой, возвращаемое значение - ПУСТО (NULL).

SendDlgItemMessage

Отправляет сообщение указанному органу управления в диалоговом окне.

Синтаксис:

LRESULT WINAPI SendDlgItemMessage(

In_ int nIDDlgItem,

In_ WPARAM wParam,

In_ LPARAM lParam

Параметры:

    hDlg - дескриптор диалогового окна, которое содержит орган управления.

    nIDDlgItem - устанавливает идентификатор органа управления, который получает сообщение.

    Msg - задает отправляемое сообщение.

    wParam - устанавливает дополнительную специальную для сообщения информацию.

    lParam - устанавливает дополнительную специальную для сообщения информацию.

Возвращаемые значения: возвращаемое значение определяет результат обработки сообщения и зависит от отправленного сообщения.

ExitProcess

Заканчивает работу процесса и всех его потоков.

Синтаксис:

VOID WINAPI ExitProcess(

In_ UINT uExitCode

Параметры:

    uExitCode - определяет код выхода для процесса, и для всех потоков, которые завершают работу в результате вызова этой функции. Используйте функцию GetExitCodeProcess, чтобы получить значение выхода из процесса. Используйте функцию GetExitCodeThread, чтобы получить значение выхода из потока.

Возвращаемые значения: у этой функции нет возвращаемого значения.

GetModuleHandle

Извлекает дескриптор указанного модуля, если файл был отображен в адресном пространстве вызывающего процесса.

Синтаксис:

HMODULE WINAPI GetModuleHandle(

In_opt_ LPCTSTR lpModuleName

Параметры:

    lpModuleName - указатель на символьную строку с нулем в конце, которая содержит имя модуля (или.dll, или.exe файл). Если расширение имени файла опускается, в конец добавляется заданное по умолчанию библиотечное расширение.dll. Символьная строка имени файла может включать в себя конечный символ точки (.), который указывает, что имя модуля не имеет расширения. Строка не должна определять путь. Когда определяется путь, убедитесь, что используются обратные слэши (\), а не прямые слэши (/).

Возвращаемые значения: если функция завершается успешно, возвращаемое значение - дескриптор указанного модули. Если функция завершается ошибкой, возвращаемое значение - NULL.

DialogBoxParam

Создает модальное диалоговое окно из шаблона ресурса блока диалога. Перед показом диалогового окна на экране, функция передает в процедуру блока диалога определяемое программой значение, такое как параметр lParam сообщения WM_INITDIALOG. Прикладная программа может использовать это значение, чтобы инициализировать органы управления диалогового окна.

Синтаксис:

INT_PTR WINAPI DialogBoxParam(

In_opt_ HINSTANCE hInstance,

In_ LPCTSTR lpTemplateName,

In_opt_ HWND hWndParent,

In_opt_ DLGPROC lpDialogFunc,

In_ LPARAM dwInitParam

Параметры:

    hInstance - дескриптор модуля, исполняемый файл которого содержит шаблон диалогового окна.

    lpTemplateName - определяет шаблон диалогового окна. Этот параметр - или указатель на строку символов с нуль-терминатором в конце, которая определяет имя шаблона диалогового окна, или целочисленное значение, которое определяет идентификатор ресурса шаблона блока диалога. Если параметр определяет идентификатор ресурса, его старшее слово должно быть нуль, а младшее слово должно содержать этот идентификатор. Вы можете использовать макрокоманду MAKEINTRESOURCE, чтобы создать это значение.

    hWndParent - дескриптор окна, которое владеет диалоговым окном.

    lpDialogFunc - указатель на процедуру диалогового окна.

    dwInitParam - устанавливает значение, передаваемое процедуре диалогового окна в параметре lParam сообщения WM_INITDIALOG.

Возвращаемые значения: если функция завершается успешно, возвращаемое значение - значение параметра nResult, заданного при вызове к функции EndDialog, используемой, чтобы завершить работу диалогового окна. Если функция завершается ошибкой, потому что параметр hWndParent недопустим, возвращаемое значение равняется нулю.

EndDialog

Уничтожает модальное диалоговое окно, заставляя систему закончить любую обработку информации диалогового окна.

Синтаксис:

BOOL WINAPI EndDialog(

In_ INT_PTR nResult

Параметры:

    hDlg - дескриптор уничтожаемого диалогового окна.

    nResult - устанавливает значение, возвращаемое прикладной программе из функции, которая создала диалоговое окно.

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

SetTimer

Создает таймер с указанным значением времени простоя.

Синтаксис:

UINT_PTR WINAPI SetTimer(

In_opt_ HWND hWnd,

In_ UINT_PTR nIDEvent,

In_ UINT uElapse,

In_opt_ TIMERPROC lpTimerFunc

Параметры:

    hWnd - дескриптор окна, которое связано с таймером. Это окно должно быть собственностью вызывающего потока. Если этот параметр NULL, никакое окно не связано с таймером, а параметр nIDEIvent игнорируется.

    nIDEvent - указывает идентификатор таймера отличный от нуля. Если параметр hWnd - NULL, этот параметр игнорируется. Если параметр hWnd - не NULL, и у окна указанного hWnd уже есть таймер со значением nIDEvent, то существующий таймер заменяется новым таймером.

    uElapse - указывает значение времени простоя, в миллисекундах.

    lpTimerFunc - указатель на функцию, которая уведомляет, когда значение времени простоя истекает. Если параметр lpTimerFunc - NULL, система помещает уведомление WM_TIMER в очередь прикладной программы.

Возвращаемое значение: если функция завершается успешно, а параметр hWnd - NULL, возвращаемое значение - целое число, идентифицирующее новый таймер. Приложение может передать это значение в функцию KillTimer, чтобы уничтожить таймер. Если функция завершается успешно, а hWnd параметр - не NULL, тогда возвращаемое значение - целое число отличное от нуля. Приложение может передать значение параметра nIDEvent в функцию KillTimer, чтобы уничтожить таймер. Если при создании таймера функция завершается ошибкой, возвращаемое значение - нуль.

KillTimer

Ликвидирует указанный таймер.

Синтаксис:

BOOL WINAPI KillTimer(

In_opt_ HWND hWnd,

In_ UINT_PTR uIDEvent

Параметры:

    hWnd - дескриптор окна, связанного с указанным таймером. Это значение должно быть таким же, как и значение hWnd, переданное в функцию SetTimer, которая создала таймер.

    uIDEvent - указывает таймер, который будет ликвидирован. Если дескриптор окна, который передают в функцию SetTimer - правильный, то этот параметр должен быть таким же, как и значение nIDEvent переданное в SetTimer. Если приложение вызывает SetTimer с hWnd установленным в NULL, то этот параметр должен быть идентификатором таймера, значение которого возвращает функция SetTimer.

Возвращаемые значения: если функция завершается успешно, возвращаемое значение - не нуль. Если функция завершается ошибкой, возвращаемое значение - нуль.

Этот краткий термин на слуху у всех, кто хоть как-то сталкивался с разработкой. Но далеко не все понимают, что именно он обозначает и зачем нужен. Разработчик Пётр Газаров рассказал об API простыми словами в своём блоге.

Аббревиатура API расшифровывается как «Application Programming Interface» (интерфейс программирования приложений, программный интерфейс приложения). Большинство крупных компаний на определённом этапе разрабатывают API для клиентов или для внутреннего использования. Чтобы понять, как и каким образом API применяется в разработке и бизнесе, сначала нужно разобраться, как устроена «всемирная паутина».

Всемирная паутина и удалённые серверы

WWW можно представить как огромную сеть связанных серверов, на которых и хранится каждая страница. Обычный ноутбук можно превратить в сервер, способный обслуживать целый сайт в сети, а локальные серверы разработчики используют для создания сайтов перед тем, как открыть их для широкого круга пользователей.

При введении в адресную строку браузера www.facebook.com на удалённый сервер Facebook отправляется соответствующий запрос. Как только браузер получает ответ, то интерпретирует код и отображает страницу.

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

API как способ обслуживания клиентов

Многие компании предлагают API как готовый продукт. Например, Weather Underground продаёт доступ к своему API для получения метеорологических данных .

Сценарий использования: на сайте небольшой компании есть форма для записи клиентов на приём. Компания хочет встроить в него Google Календарь, чтобы дать клиентам возможность автоматически создавать событие и вносить детали о предстоящей встрече.

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

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

Чем API Google Календаря отличается от API любого другого удалённого сервера в сети?

Технически, разница в формате запроса и ответа. Чтобы сгенерировать полную веб-страницу, браузер ожидает ответ на языке разметки HTML, в то время как API Google Календаря вернёт просто данные в формате вроде JSON.

Если запрос к API делает сервер веб-сайта компании, то он и является клиентом (так же, как клиентом выступает браузер, когда пользователь открывает веб-сайт).

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

Большинство современных сайтов используют по крайней мере несколько сторонних API. Многие задачи уже имеют готовые решения, предлагаемые сторонними разработчиками, будь то библиотека или услуга. Зачастую проще и надёжнее прибегнуть именно к уже готовому решению.

Многие разработчики разносят приложение на несколько серверов, которые взаимодействуют между собой при помощи API. Серверы, которые выполняют вспомогательную функцию по отношению к главному серверу приложения, называются микросервисами .

Таким образом, когда компания предлагает своим пользователям API, это просто означает, что она создала ряд специальных URL, которые в качестве ответа возвращают только данные.

Такие запросы часто можно отправлять через браузер. Так как передача данных по протоколу HTTP происходит в текстовом виде, браузер всегда сможет отобразить ответ. Например, через браузер можно напрямую обратиться к API GitHub (https://api.github.com/users/petrgazarov), причём без маркера доступа, и получить вот такой ответ в формате JSON:

Браузер отлично отображает JSON-ответ, который вполне можно вставлять в код. Из такого текста достаточно просто извлечь данные, чтобы использовать их по своему усмотрению.

Ещё несколько примеров API

Слово «application» (прикладной, приложение) может применяться в разных значениях. В контексте API оно подразумевает:

Любой фрагмент ПО, который можно чётко выделить из окружения, может заменять букву «А» в англоязычной аббревиатуре, и тоже может иметь некоторого рода API. Например, при внедрении в код разработчиком сторонней библиотеки, она становится частью всего приложения. Будучи самостоятельным фрагментом ПО, библиотека будет иметь некий API, который позволит ей взаимодействовать с остальным кодом приложения.

В объектно-ориентированном проектировании код представлен в виде совокупности объектов. В приложении таких объектов, взаимодействующих между собой, могут быть сотни. У каждого из них есть свой API — набор публичных свойств и методов для взаимодействия с другими объектами в приложении. Объекты могут также иметь частную , внутреннюю логику, которая скрыта от окружения и не является API.

Диктую По Буквам имеет простой REST API который позволяет:

Все функции API поддерживают метод JSONP : если запрос содержит параметр callback=functionName , JSON-ответ сервера будет завёрнут в вызов функции functionName .

Получение списка алфавитов

Чтобы получить список доступных алфавитов, отправьте GET-запрос следующего формата:

http://api.?format=json [&callback=functionName ]

Сервер вернёт JSON-массив с краткой информацией о доступных алфавитах. [ { "id" :"int-icao" , "language" :"Международные" , "name" : }, { "id" :"de-default" , "language" :"Немецкий" , "name" :"Немецкий фонетический алфавит" }, { "id" :"ru-avia" , "language" :"Русский" , "name" :"Русский авиационный радиоалфавит" } ]

Элементы массива имеют следующие поля: id Идентификатор алфавита, используемый для указания нужного алфавита в других функциях API. language Язык, для которого используется данный алфавит. Для алфавитов, не привязанных к какому-либо конкретному языку, это поле содержит значение "Международные". name Название алфавита на русском языке.

Получение подробной информации об алфавите

Чтобы получить информацию о конкретном алфавите, нужно отправить GET-запрос со следующими параметрами:

http://api.?alphabet=int-icao &format=json [&callback=functionName ]

Параметры запроса имеют следующее назначение: alphabet Идентификатор алфавита. Список доступных алфавитов (и их ID) можно получить . format Желаемый формат ответа. Если format=json , результат запроса будет JSON-строкой, в других случаях ответ будет в HTML-формате.

"Международный фонетический алфавит ИКАО" , "description" :, "source" :{ "name" :"ICAO" , "url" : } } }

Объект alphabet имеет следующие поля: id Идентификатор алфавита. language Язык, для которого используется данный алфавит. Для алфавитов, не привязанных к какому-либо конкретному языку, это поле содержит значение "Международные". name Название алфавита на русском языке. description Описание алфавита, его история, варианты использования, другая полезная информация. source Источник информации об алфавите:

  • name — название источника (имя человека, название книги или сайта).
  • url — гиперссылка на источник (если существует).

Преобразование текста

Чтобы преобразовать по буквам текст, нужно отправить GET или POST запрос со следующими параметрами:

http://api.?text=some%20text &alphabet=int-icao &format=json [&callback=functionName ]

Параметры запроса имеют следующий смысл: text Текст для конверсии (URL-encoded). Максимальная длина текста — 200 символов, остальные будут проигнорированы. alphabet Идентификатор алфавита, который будет использован для преобразования. Список доступных алфавитов (и их ID) можно получить . format Желаемый формат ответа. Если format=json , результат запроса будет JSON-строкой, в других случаях ответ будет в HTML-формате.

Ниже приведён пример ответа сервера (отформатированный для наглядности):

{ "alphabet" :{ "id" :"int-icao" , "language" :"Международные" , "name" :"Международный фонетический алфавит" , "description" :"Фонетический алфавит международной авиационной организации, также известный как международный радиотелефонный алфавит..." , "source" :{ "name" :"ИКАО" , "url" :"http://www.icao.int/icao/en/trivia/alphabet.htm" } }, "spelling" :[ { "original" :"h" , "spelling" :"Hotel" , "format" :"text" , "isGeneric" :false , "midWord" :"for" }, { "original" :"i" , "spelling" :"India" , "format" :"text" , "isGeneric" :false , "midWord" :"for" }, { "original" :"!" , "spelling" :"exclamation mark" , "format" :"text" , "isGeneric" :true , "isPunct" :true } ] }

Элементы массива spelling имеют следующие поля: original Один или несколько символов исходного текста (например, "h", "ae" или "sch"), в виде url-encoded строки. spelling Кодовое слово ассоциированное с исходным символом (url-encoded строка). Формат содержимого определяется полем format . format (необязательный) Формат поля spelling . Может принимать одно из следующих значений:

  • "text" — Поле spelling содержит HTML или простой текст.
  • "img" — Поле spelling содержит ссылку на изображение или само изображение (закодированное в data:URI).
Если поле format не задано, по умолчанию принимается формат "text". isGeneric Указывает, взято ли правило конверсии из самого алфавита (false). Если использованный алфавит не содержит правила для данного исходного символа (например, для знаков пунктуации), правило берётся из набора общих правил для данного языка (true). translation (необязательный) Вспомогательное кодовое слово (в url-encoded виде). Это может быть или перевод слова указанного в spelling, или альтернативное кодовое слово ("а" — "Антон", "Александр"). Если spelling задаёт изображение (format="img"), translation задаёт текстовое описание этой картинки, которое можно поместить в атрибут "alt" тега . midWord (необязательный) Слово-связка (на языке алфавита), используемое между исходной буквой и кодовым словом (url-encoded строка). Например, "a for Alpha" (по-английски), "b come Bologna" (по-итальянски), и т.п. isPunct (необязательный) Указывает, является ли исходный символ символом пунктуации (true ) или буквой/цифрой (false ). Если поле isPunct не задано, по умолчанию принимается значение false .