API функции языка Visual Basic. Что такое API Api функции

Windows API - набор функций операционной системы

Аббревиатура API многим начинающим программистам кажется весьма таинственной и даже пугающей. На самом же деле Application Programming Interface (API) - это просто некоторый готовый набор функций, который могут использовать разработчики приложений. В общем случае данное понятие эквивалентно тому, что раньше чаще называли библиотекой подпрограмм. Однако обычно под API подразумевается особая категория таких библиотек.

В ходе разработки практически любого достаточно сложного приложения (MyAppication) для конечного пользователя формируется набор специфических внутренних функций, используемых для реализации данной конкретной программы, который называется MyApplication API. Однако часто оказывается, что эти функции могут эффективно использоваться и для создания других приложений, в том числе другими программистами. В этом случае авторы, исходя из стратегии продвижения своего продукта, должны решить вопрос: открывают они доступ к этому набору для внешних пользователей или нет? При утвердительном ответе в описании программного пакета в качестве положительной характеристики появляется фраза: «Комплект включает открытый набор API-функций» (но иногда за дополнительные деньги).

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

Соответственно Windows API - это набор функций, являющийся частью самой операционной системы и в то же время - доступный для любого другого приложения, в том числе написанного с помощью VB. В этом плане вполне оправданна аналогия с набором системных прерываний BIOS/DOS, который фактически представляет собой DOS API.

Отличие заключается в том, что состав функций Windows API, с одной стороны, значительно шире по сравнению с DOS, с другой - не включает многие средства прямого управления ресурсами компьютера, которые были доступны программистам в предыдущей ОС. Кроме того, обращение к Windows API выполняется с помощью обыкновенных процедурных обращений, а вызов функций DOS - через специальную машинную команду процессора, которая называется Interrupt («прерывание»).

Зачем нужен Win API для VB-программистов

Несмотря на то что VB обладает огромным множеством разнообразных функций, в процессе более-менее серьезной разработки обнаруживается, что их возможностей зачастую не достаточно для решения необходимых задач. При этом программисты-новички часто начинают жаловаться на недостатки VB и подумывать о смене инструмента, не подозревая, что на их компьютере имеется огромный набор средств и нужно только уметь ими воспользоваться.

При знакомстве с Win API обнаруживается, что многие встроенные VB-функции - не что иное, как обращение к соответствующим системным процедурам, но только реализованное в виде синтаксиса данного языка. С учетом этого необходимость использования API определяется следующим вариантами:

1. API-функции, которые полностью реализованы в виде встроенных VB-функций. Тем не менее иногда и в этом случае бывает полезным перейти к применению API, так как это позволяет порой существенно повысить производительность (в частности, за счет отсутствия ненужных преобразований передаваемых параметров).
2. Встроенные VB-функции реализуют лишь частный случай соответствующей API-функции. Это довольно обычный вариант. Например, API-функция CreateDirectory обладает более широкими возможностями по сравнению со встроенным VB-оператором MkDir.
3. Огромное число API-функций вообще не имеет аналогов в существующем сегодня варианте языка VB. Например, удалить каталог средствами VB нельзя - для этого нужно использовать функцию DeleteDirectory.

Следует также подчеркнуть, что некоторые API-функции (их доля в Win API весьма незначительна) не могут вызываться из VB-программ из-за ряда ограничений языка, например из-за отсутствия возможности работы с адресами памяти. Но в ряде случаев могут помочь нетривиальные приемы программирования (в частности, в случае с теми же адресами).

Личная точка зрения автора такова - вместо расширения от версии к версии встроенных функций VВ следовало бы давать хорошее описание наиболее ходовых API-функций. В то же время хочется посоветовать разработчикам не ждать появления новой версии средства с расширенными функциями, а внимательнее изучить состав существующего Win API - вполне вероятно, что нужные вам возможности можно было реализовать уже в версии VB 1.0 выпуска 1991 года.

Как изучать Win API

Это не такой простой вопрос, если учесть, что число функций Win32 API оценивается величиной порядка 10 тысяч (точной цифры не знает никто, даже Microsoft).

В состав VB (версий 4-6) входит файл с описанием объявлений Win API - WIN32API.TXT (подробнее о его применении мы расскажем позднее). Но, во-первых, с его помощью можно получить сведения о назначении той или иной функции и ее параметрах только по используемым мнемоническим именам, а во-вторых - перечень функций в этом файле далеко не полный. В свое время (семь лет назад) в VB 3.0 имелись специальные справочные файлы с описанием функций Win16 API. Однако уже в v.4.0 эта полезная информация с удобным интерфейсом исчезла.

Исчерпывающую информацию о Win32 API можно найти в справочной системе Platform Software Development Kit, которая, в частности, находится на компакт-дисках MSDN Library, включенных в состав VB 5.0 и 6.0 Enterprise Edition и Office 2000 Developer Edition. Однако разыскать там нужную информацию и разобраться в ней совсем не просто. Не говоря уж о том, что все описания там приводятся применительно к языку C.

Общепризнанным в мире пособием для изучения API-программирования в среде VB являются книги известного американского эксперта Даниэля Эпплмана (Daniel Appleman). Его серия Dan Appleman’s Visual Basic Programmer’s Guide to the Windows API (для Win16, Win32, применительно к разным версиям VB) с 1993 года неизменно входит в число бестселлеров для VB-программистов. Книгу Dan Appleman’s VB 5.0 Programmer’s Guide to the Win32 API, выпущенную в 1997 году, автору привез из США приятель, который нашел ее в первом же книжном магазине небольшого провинциального городка.

Эта книга объемом свыше 1500 страниц включает описание общей методики API-программирования в среде VB, а также более 900 функций. Прилагаемый компакт-диск содержит полный текст книги и всех программных примеров, а кроме того, несколько дополнительных глав, не вошедших в печатный вариант. В 1999 году Дэн Эпплман выпустил новую книгу Dan Appleman’s Win32 API Puzzle Book and Tutorial for Visual Basic Programmers, которая включает сведения о еще 7600 функциях (хотя и не столь обстоятельные).

Win API и Dynamic Link Library (DLL)

Набор Win API реализован в виде динамических DLL-библиотек. Далее речь фактически пойдет о технологии использования DLL в среде VB на примере библиотек, входящих в состав Win API. Однако, говоря о DLL, необходимо сделать несколько важных замечаний.

В данном случае под DLL мы подразумеваем традиционный вариант двоичных динамических библиотек, которые обеспечивают прямое обращение приложений к нужным процедурам - подпрограммам или функциям (примерно так же, как это происходит при вызове процедур внутри VB-проекта). Такие библиотеки могут создаваться с помощью разных инструментов: VC++, Delphi, Fortran, кроме VB (посмотрим, что появится в версии 7.0) - последний может делать только ActiveX DLL, доступ к которым выполняется через интерфейс OLE Automation.

Обычно файлы динамических библиотек имеют расширение.DLL, но это совсем не обязательно (для Win16 часто применялось расширение.EXE); драйверы внешних устройств обозначаются с помощью.DRV.

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

А теперь несколько советов.

Совет 1. Следите за правильным оформлением объявления DL L-процедур

Само обращение к DLL-процедурам в программе выглядит точно так же, как к «обычным» процедурам Visual Basic, например:

Call DllName ([список аргументов])

Однако для использования внешних DLL-функций (в том числе и Win API) их нужно обязательно объявить в программе с помощью оператора Declare, который имеет следующий вид:

Declare Sub ИмяПроцедуры Lib _ “ИмяБиблиотеки” _ [([СписокАргументов])]

Declare Function ИмяФункции _ Lib “ИмяБиблиотеки” _ [([СписокАргументов])]

Здесь в квадратных скобках приведены необязательные элементы оператора, курсивом выделены переменные выражения, остальные слова - ключевые. В справочной системе приведено достаточно хорошее описание синтаксиса оператора, поэтому сейчас мы только отметим некоторые моменты.

Объявления внешних функций должны размещаться в секции General Declarations модуля. Если вы размещаете его в модуле формы, то обязательно нужно указать ключевое слово Private (это объявление будет доступно только внутри данного модуля) - таково ограничение для всех процедур модуля формы.

Набор Win32 API реализован только в виде функций (в Win16 API было много подпрограмм Sub). В большинстве своем - это функции типа Long, которые чаще всего возвращают код завершения операции.

Оператор Declare появился в MS Basic еще во времена DOS, причем он использовался и для объявления внутренних процедур проекта. В Visual Basic этого не требуется, так как объявлением внутренних процедур автоматически является их описание Sub или Function. По сравнению с Basic/DOS в новом описании обязательно указывать имя файла-библиотеки, где находится искомая процедура. Библиотеки Wip API размещаются в системном каталоге Windows, поэтому достаточно привести только название файла. Если же вы обращаетесь к DLL, которая находится в произвольном месте, нужно записать полный путь к данному файлу.

Описание оператора Declare обычно занимает довольно много места и не помещается в одну строку в окне кода. Поэтому мы рекомендуем придерживаться при написании приложений какой-либо определенной схемы переноса строк, например:

Declare Function GetTempPath _ Lib “kernel32” Alias “GetTempPathA” _ (ByVal nBufferLength As Long, _ ByVal lpBuffer As String) As Long

В этом случае все основные элементы описания разнесены на разные строчки и поэтому хорошо читаются.

Совет 2. Будьте особенно внимательны при работе с DLL-функциями

Использование Win API и разнообразных DLL-функций существенно расширяет функциональные возможности VB и зачастую позволяет повысить производительность программ. Однако расплата за это - риск снижения надежности работы приложения, особенно в процессе его отладки.

Одним из самых важных достоинств среды VB является надежность процесса разработки программ: функционируя под управлением интерпретатора, программный код теоретически не может нарушить работу Windows и самого VB. Программист может не очень внимательно следить за правильностью передачи параметров в вызываемые функции - подобные ошибки будут легко обнаружены самим интерпретатором либо в процессе трансляции кода, либо во время его выполнения. В самом неприятном случае просто произойдет прерывание режима обработки, причем с указанием, где и почему произошла ошибка.

Использование напрямую функций Windows API или других DLL-библиотек снимает такой контроль за передачей данных и процессом выполнения кода вне среды VB. Поэтому ошибка в обращении к внешним функциям может привести к неработоспособности и VB и операционной системы. Это особенно актуально на этапе разработки программы, когда наличие ошибок - дело вполне естественное. Таким образом, применяя более широкие возможности функций базового слоя системы, программист берет на себя ответственность за правильность их применения.

Проблема усугубляется еще и тем, что разные языки программирования используют различные способы передачи параметров между процедурами. (Точнее, разные способы передачи используются по умолчанию, так как многие языки могут поддерживать несколько способов.) Win API реализованы на C/C++ и применяют соглашения о передаче параметров, принятые в этой системе, которые отличаются от привычного для VB варианта.

В связи с этим следует отметить, что появление встроенных в VB аналогов API-функций оправданно именно адаптацией последних к синтаксису VB и реализацией соответствующего механизма контроля обмена данными. Обратим также внимание, что на этапе опытной отладки приложения при создании исполняемого модуля лучше использовать вариант компиляции P-code вместо Native Code (машинный код). В первом случае программа будет работать под управлением интерпретатора - медленнее по сравнению с машинным кодом, но более надежно с точки зрения возможного ошибочного воздействия на операционную систему и обеспечивая более удобный режим выявления возможных ошибок.

Совет 3. Десять рекомендаций Дэна Эпплмана по надежному API-программированию в среде VB

Использование функции API требует более внимательного программирования с использованием некоторых не очень привычных методов обращения к процедурам (по сравнению с VB). Далее мы будем постоянно обращаться к этим вопросам. А сейчас приведем изложение сформулированных Дэном Эпплманом советов на эту тему (их первый вариант появился еще в 1993 году) с некоторыми нашими дополнениями и комментариями.

1. Помните о ByVal. Наиболее частая ошибка, совершаемая при обращении к функциям API и DLL, заключается в некорректном использовании ключевого слова ByVal: его или забывают ставить, или, наоборот, ставят, когда в нем нет необходимости.

На этих примерах показано влияние оператора ByVal на передачу параметров

Тип параметра	С ByVal	Без ByVal
Integer	В стек помещается 16-разрядное целое	В стек помещается 32-разрядный адрес 16-разрядного целого
Long	В стек помещается 32-разрядное целое	В стек помещается 32-разрядный адрес 32-разрядного целого
String	Строка преобразуется в формат, используемый в С (данные и завершающий нулевой байт). 32-разрядный адрес новой строки помещается в стек	В стек помещается VB-дескриптор строки. (Такие дескрипторы никогда не используются самим Windows API и распознаются только в DLL, реализованных специально для VB.)

Здесь следует напомнить, что передача параметров в любой системе программирования, в том числе и VB, выполняется двумя основными путями: по ссылке (ByRef) или по значению (ByVal). В первом случае передается адрес переменной (этот вариант используется в VB по умолчанию), во втором - ее величина. Принципиальное отличие заключается в том, что с помощью ссылки обеспечивается возврат в вызывающую программу измененного значения передаваемого параметра.

Чтобы разобраться в этом, проведите эксперимент с помощью таких программ:

Dim v As Integer v = 2 Call MyProc(v) MsgBox “v = “ & v Sub MyProc (v As Integer) v = v + 1 End Sub

Запустив на выполнение этот пример, вы получите сообщение со значением переменной, равным 3. Дело в том, что в данном случае в подпрограмму MyProc передается адрес переменной v, физически созданной в вызывающей программе. Теперь измените описание процедуры на

Sub MyProc (ByVal v As Integer)

В результате при выполнении теста вы получите v = 2, потому что в процедуру передается лишь исходное значение переменной - результат выполненных с ним операций не возвращается в вызывающую программу. Режим передачи по значению можно поменять также с помощью оператора Call следующим образом:

Sub MyProc (v As Integer) ... Call MyProc((v)) ‘ (v) - скобки указывают режим _ передачи по значению.

Однако при обращении к внутренним VB-процедурам использование в операторе Call ключевого слова ByVal запрещено - вместо него применяются круглые скобки. Этому есть свое объяснение.

В классическом случае (С, Fortran, Pascal) различие режимов ByRef и ByVal зависит от того, что именно помещается в стек обмена данными - адрес переменной или ее значение. В Basic исторически используется вариант программной эмуляции ByVal - в стеке всегда находится адрес, но только при передаче по значению для этого создается временная переменная. Чтобы отличить два этих варианта (классический и Basic), используются разные способы описания режима ByVal. Отметим, что эмуляция режима ByVal в VB обеспечивает более высокую надежность программы: перепутав форму обращения, программист рискует лишь тем, что в вызывающую программу вернется (или не вернется) исправленное значение переменной. В «классическом» же варианте такая путаница может привести к фатальной ошибке при выполнении процедуры (например, когда вместо адреса памяти будет использоваться значение переменной, равное, скажем, нулю).

DLL-функции реализованы по «классическим» принципам и поэтому требуют обязательного описания того, каким образом происходит обмен данными с каждым из аргументов. Именно этой цели служат объявления функций через описание Declare (точнее, списка передаваемых аргументов). Чаще всего передача параметров в функцию Windows API или DLL выполняется с помощью ключевого слова ByVal. Причем оно может быть задано как в операторе Declare, так и непосредственно при вызове функции.

Последствия неправильной передачи параметров легко предугадать. В случае получения явно недопустимого адреса вам будет выдано сообщение GPF (General Protection Fault - ошибка защиты памяти). Если же функция получит значение, совпадающее с допустимым адресом, то функция API залезет в чужую область (например, в ядро Windows) со всеми вытекающими отсюда катастрофическими последствиями.

2. Проверяйте тип передаваемых параметров. Не менее важны верное число и тип передаваемых параметров. Необходимо, чтобы объявленные в Declare аргументы соответствовали ожидаемым параметрам в функции API. Наиболее часто встречающийся случай ошибки в передаче параметров связан с различием между NULL и строкой нулевой длины - следует помнить, что это не одно и то же.

3. Проверяйте тип возвращаемого значения.

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

• DLL-функция, не возвращающая значения (аналог void в ‘C’), должна быть объявлена как VB Sub.
• функция API, возвращающая целое значение (Integer или Long), может быть определена или как Sub, или как Function, возвращающая значение соответствующего типа.
• ни одна из функций API не возвращает числа с плавающей точкой, но некоторые DLL вполне могут возвращать такой тип данных.

4. С большой осторожностью используйте конструкцию «As Any». Множество функций Windows API имеют возможность принимать параметры различных типов и используют при этом обращение с применением конструкции As Any (интерпретация типа выполняется в зависимости от значения других передаваемых параметров).

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

5. Не забывайте инициализировать строки. В Win API существует множество функций, возвращающих информацию путем загрузки данных в передаваемые как параметр строковые буферы. В своей программе вы можете вроде бы все сделать правильно: не забыть о ByVal, верно передать параметры в функцию. Но Windows не может проверить, насколько велик размер выделенного под строку участка памяти. Размер строки должен быть достаточным для размещения всех данных, которые могут быть в него помещены. Ответственность за резервирование буфера нужного размера лежит на VB-программисте.

Следует отметить, что в 32-разрядных Windows при использовании строк производится преобразование из Unicode (двухбайтовая кодировка) в ANSI (однобайтовая) и обратно, причем с учетом национальных установок системы. Поэтому для резервирования буферов порой удобнее использовать байтовые массивы вместо строковых переменных. (Подробнее об этом будет рассказано ниже.)

Чаще всего функции Win API позволяют вам самим определить максимальный размер блока. В частности, иногда для этого нужно вызвать другую функцию API, которая «подскажет» размер блока. Например, GetWindowTextLength позволяет определить размер строки, необходимый для размещения заголовка окна, получаемого функцией GetWindowText. В этом случае Windows гарантирует, что вы не выйдете за границу.

6. Обязательно используйте Option Explicit.

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

Windows 9x обладает усовершенствованной системой проверки параметров для большинства функций API. Поэтому наличие ошибки в данных обычно не вызывает фатальной ошибки, однако определить, что же явилось ее причиной - не так-то просто.

Здесь можно посоветовать использовать несколько способов отладки ошибки данного типа:

• используйте пошаговый режим отладки или команду Debug.Print для проверки каждого подозрительного вызова функции API. Проверьте результаты этих вызовов, чтобы удостовериться, что все в пределах нормы и функция корректно завершилась;
• используйте Windows-отладчик типа CodeView и отладочную версию Windows (имеется в Windows SDK). Эти средства могут обнаружить ошибку параметров и по меньшей мере определить, какая функция API приводит к ошибке;
• используйте дополнительные средства третьих фирм для проверки типов параметров и допустимости их значений. Такие средства могут не только находить ошибки параметров, но даже указать на строку кода VB, где произошла ошибка.

Кроме того, нужно обязательно проверять результат выполнения API-функции.

8. Помните, что целые числа в VB и в Windows - не одно и то же. В первую очередь следует иметь в виду, что под термином «Integer» в VB понимается 16-разрядное число, в документации Win 32 - 32-разрядное. Во-вторых, целые числа (Integer и Long) в VB - это величины со знаком (то есть один разряд используется как знак, остальные - как мантисса числа), в Windows - используются только неотрицательные числа. Это обстоятельство нужно иметь в виду, когда вы формируете передаваемый параметр с помощью арифметических операций (например, вычисляете адрес с помощью суммирования некоторой базы и смещения). Для этого стандартные арифметические функции VB не годятся. Как быть в этом случае, мы поговорим отдельно.

9. Внимательно следите за именами функций. В отличие от Win16 имена всех функций Win32 API являются чувствительными к точному использованию строчных и прописных букв (в Win16 такого не было). Если вы где-то применяете строчную букву вместо прописной или наоборот, то нужная функция не будет найдена. Следите также за правильным использованием суффикса A или W в функциях, применяющих строковые параметры. (Подробнее об этом – см. ниже.)

10. Чаще сохраняйте результаты работы. Ошибки, связанные с неверным использованием DLL и Win API, могут приводить к аварийному завершению работы VB-среды, а возможно - и всей операционной системы. Вы должны позаботиться о том, чтобы написанный вами код перед тестовым запуском был сохранен. Самое простое - это установить режим автоматической записи модулей проекта перед запуском проекта в среде VB.

После прочтения предыдущего совета может возникнуть мысль, что использование функций Win API - дело рискованное. В какой-то степени это так, но только в сравнении с безопасным программированием, предоставляемым самим VB. Но при умелом их применении и знании возможных подводных камней этот риск минимален. К тому же полностью отказаться от применения Win API зачастую просто невозможно - они все равно потребуются при сколь-нибудь серьезной разработке.

К тому же ранее мы упоминали о «подводных» камнях для широкого класса DLL. В случае с Win API все обстоит гораздо проще, так как здесь четко унифицирована форма обращения к этим функциям. При этом следует иметь в виду следующие основные моменты:

1. Функции Win32 API являются именно функциями, то есть процедурами типа Function (в Win16 API было много подпрограмм Sub). Все это функции типа Long, поэтому их описания записываются в следующем виде: Declare Function name ... As Long ‘ тип функции _ определяется в явном виде

   Declare Function name& ‘ тип функции _ определяется с помощью суффикса

   Обращение к API-функции выглядит так:

Result& = ApiName& ([СписокАргументов ]

1. Чаще всего возвращаемое значение функции является кодом завершения операции. Причем ненулевое значение означает в данном случае нормальное завершение, нулевое - ошибку. Обычно (но не всегда) уточнить характер ошибки можно с помощью обращения к функции GetLastError. Описание этой функции имеет такой вид: Declare Function GetLastError& Lib “kernel32” ()

   ВНИМАНИЕ! При работе в среде VB для получения значения уточненного кода ошибки лучше использовать свойство LastDLLError объекта Err, так как иногда VB обнуляет функцию GetLastError в промежутке между обращением к API и продолжением выполнения программы.

   Интерпретировать код, возвращаемый GelLastError, можно с помощью констант, записанных в файле API32.TXT, с именами, начинающимися с суффикса ERROR_.

   Наиболее типичные ошибки имеют следующие коды:

   • ERROR_INVALID_HANDLE = 6& - неверный описатель
   • ERROR_CALL_NOT_IMPLEMENTED = 120& - вызов в Windows 9x функции, доступной только для Windows NT
   • ERROR_INVALID_PARAMETER = 87& - неверное значение параметра

   Однако многие функции возвращают значение некоторого запрашиваемого параметра (например, OpenFile возвращает значение описателя файла). В таких случаях ошибка определяется каким-либо другим специальным значением Return&, чаще всего 0 или –1.

2. Win32 API используют строго фиксированные способы передачи самых простых типов данных. а) ByVal ... As Long

   С помощью переменных типа Long выполняется не менее 80% передачи аргументов. Обратите внимание, что аргумент всегда сопровождается ключевым словом ByVal, а это, кроме всего прочего, означает, что выполняется односторонняя передача данных - от VB-программы к API-функции.

   Б) ByVal ... As String

   Этот тип передачи данных также встречается достаточно часто, причем с аргументом также всегда применяется ByVal. При вызове API-функции в стек записывается адрес строки, поэтому в данном случае возможен двусторонний обмен данными. При работе со строками нужно учитывать несколько опасностей.

   Первая - резервирование памяти под строку производится в вызывающей программе, поэтому если API-функция будет заполнять строки, то нужно перед ее вызовом создать строку необходимого размера. Например, функция GetWindowsDirectory возвращает путь к каталогу Windows, который по определению не должен занимать более 144 символов. Соответственно обращение к этой функции должно выглядеть примерно так:

   WinPath$ = Space$(144) ‘ резервируем строку в _ 144 символа Result& = GetWindowsDirectory& (WinTath$, 144) _ ‘заполнение буфера ‘ Result& - фактическое число символов в имени _ каталога WinPath$ = Left$(WinPath, Result&)

   Вторая проблема заключается в том, что при обращении к API-функции производится преобразование исходной строки в ее некоторое внутреннее представление, а при выходе из функции - наоборот. Если во времена Win16 эта операция заключалась лишь в добавлении нулевого байта в конце строки, то с появлением Win32 к этому добавилась трансформация двухбайтной кодировки Unicode в ANSI и наоборот. (Об этом подробно говорилось в статье «Особенности работы со строковыми переменными в VB», КомпьютерПресс 10’99 и 01’2000). Сейчас же только отметим, что с помощью конструкции ByVal ... As String можно обмениваться строками только с символьными данными.

   В) ... As Any

   Это означает, что в стек будет помещен некоторый адрес буфера памяти, интерпретация содержимого которого будет выполняться API-функцией, например, в зависимости от значения других аргументов. Однако As Any может использоваться только в операторе Declare - при конкретном обращении к функции в качестве аргумента должна быть определена конкретная переменная.

   Г) ... As UserDefinedType

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

   Форма структуры данных определяется конкретной API-функцией, и на программисте лежит ответственность правильным образом описать и зарезервировать ее в вызывающей программе. Такая конструкция всегда используется без слова ByVal, то есть в данном случае выполняется передача по ссылке - в стек записывается адрес переменной.

Пример обращения к API-функции

Проиллюстрируем сказанное выше на примере использования двух полезных функций работы с файлами - lopen и lread, которые описываются следующим образом:

Declare Function lopen Lib “kernel32” _ Alias “_lopen” (_ ByVal lpFileName As String, _ ByVal wReadWrite As Long) As Long Declare Function lread Lib “kernel32” _ Alias “_lread” (_ ByVal hFile As Long, lpBuffer As Any, _ ByVal wBytes As Long) As Long

В VB их аналогами - в данном случае точными - являются операторы Open и Get (для режима Binary). Обратим сразу внимание на использование ключевого слова Alias в объявлении функции - это как раз тот случай, когда без него не обойтись. Настоящие названия функции в библиотеке начинаются с символа подчеркивания (типичный стиль для языка C), что не разрешается в VB.

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

Const INVALID_HANDLE_VALUE = -1 ‘ неверное _ значение описателя lpFileName$ = “D:\calc.bas” ‘ имя файла wReadWrite& = 2 ‘ режим “чтения-записи” hFile& = lopen(lpFileName$, wReadWrite&) _ ‘ определяем описатель файла If hFile& = INVALID_HANDLE_VALUE Then _ ‘ ошибка открытия файла ‘ уточняем код ошибки CodeError& = Err.LastDllError ‘CodeError& = GetLastError _ ‘ эта конструкция не работает End If

Здесь нужно обратить внимание на два момента:

• в качестве значения функции мы получаем значение описателя файла. Ошибке соответствует значение –1;
• как раз в данном случае не срабатывает обращение к функции GetLastError - для получения уточненного значения ошибки мы обратились к объекту Err (о возможности такой ситуации мы говорили выше).

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

Dim MyVar As Single wBytes = lread (hFile&, MyVar, Len(MyVar) ‘ чтение вещественного числа, 4 байта ‘ wBytes - число фактически прочитанных данных, ‘ -1 - ошибка... Type MyStruct x As Single i As Integer End Type Dim MyVar As MyStruct wBytes = lread (hFile&, MyVar, Len(MyVar)) ‘ чтение структуры данных, 6 байтов

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

Dim MyVar As String MyVar = Space$(10) ‘резервируем переменную для 10 символов wBytes = lread (hFile&, ByVal MyVar, Len(MyVar)) ‘ чтение символьной строки, 10 символов

Здесь видно важное отличие от приведенного ранее примера - строковая переменная обязательно сопровождается ключевым словом ByVal.

Чтение содержимого файла в массиве (для простоты будем использовать одномерный байтовый массив) выполняется следующим образом:

Dim MyArray(1 To 10) As Byte wBytes = lread (hFile&, MyArray(1), _ Len(MyArray(1))* 10) ‘ чтение 10 элементов массива

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

WBytes = lread (hFile&, MyArray(4), _ Len(MyArray(1))* 5) ‘ чтение элементов массива с 4-го по 8-й

Совет 5. Используйте Alias для передач и параметров As Any

Здесь на основе предыдущего примера мы раскроем суть четвертого совета Дэна Эпплмана.

Работая с функцией lread, следует помнить, что при обращении к ней с использованием строковой переменной необходимо использовать ключевое слово ByVal (иначе сообщения о нелегальной операции не избежать). Чтобы обезопасить себя, можно сделать дополнительное специальное описание этой же функции для работы только со строковыми переменными:

Declare Function lreadString Lib “kernel32” _ Alias “_lread” (_ ByVal hFile As Long, ByVal lpBuffer As String, _ ByVal wBytes As Long) As Long

При работе с этим описанием указывать ByVal при обращении уже не нужно:

WBytes = lreadString (hFile&, MyVarString, _ Len(MyVarString)) ‘

Казалось бы, синтаксис оператора Declare позволяет сделать подобное специальное описание для массива:

Declare Function lreadString Lib “kernel32” Alias “_lread” (_ ByVal hFile As Long, lpBuffer() As Byte, _ ByVal wBytes As Long) As Long

Однако обращение

WBytes = lreadArray (hFile&, MyArray(), 10)

неизбежно приводит к фатальной ошибке программы.

Это продолжение разговора об особенностях обработки строковых переменных в Visual Basic: VB использует двухбайтную кодировку Unicode, Win API - однобайтную ANSI (причем с форматом, принятым в С, - с нулевым байтом в конце). Соответственно при использовании строковых переменных в качестве аргумента всегда автоматически производится преобразование из Unicode в ANSI при вызове API-функции (точнее, DLL-функции) и обратное преобразование при возврате.

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

Как известно, тип String можно использовать для описания пользовательской структуры. В связи с этим нужно помнить следующее:

• Категорически нельзя использовать для обращения к Win API конструкцию следующего вида: Type MyStruct x As Single s As String ‘ строка переменной длины End Type

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

• Можно использовать в качестве элемента структуры строку фиксированной длины: Type MyStruct x As Single s As String*8 ‘ строка фиксированной длины End Type

При этом производится соответствующее преобразование кодировок.

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

Вполне вероятно, что у вас возникнет ситуация, когда вам потребуется написать собственную библиотеку DLL-функций. Потребность в этом неизбежно появится, если вы будете использовать технологию смешанного программирования - использования двух или более языков программирования для реализации одного приложения.

Отметим в связи с этим, что смешанное программирование - это вполне обычное явление для реализации достаточно сложного приложения. Действительно, каждый язык (точнее, система программирования на базе языка) имеет свои сильные и слабые стороны, поэтому вполне логично использовать преимущества различных инструментов для решения разных задач. Например, VB - для создания пользовательского интерфейса, С - для эффективного доступа к системным ресурсам, Fortran - для реализации численных алгоритмов.

Мнение автора таково: сколь-нибудь серьезное занятие программированием требует от разработчика владения по крайней мере двумя инструментами. Разумеется, в современных условиях четкого разделения труда очень сложно быть отличным экспертом даже по двум системам, поэтому более логичной является схема «основной и вспомогательный языки». Идея здесь заключается в том, что даже поверхностное знание «вспомогательного» языка (написание довольно простых процедур) может очень заметно повысить эффективность применения «основного». Отметим, что знание VB хотя бы в качестве вспомогательного является сегодня практически обязательным требованием для профессионального программиста. Кстати, во времена DOS для любого программиста, в том числе Basic, было крайне желательным знание основ Ассемблера.

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

При изучении межпроцедурного интерфейса следует обратить внимание на следующие возможные «подводные камни»:

• Разные языки могут использовать различные соглашения о правилах написания идентификаторов. Например, часто используется знак подчеркивания в начале имени процедуры, что запрещено в VB. Эта проблема легко решается с помощью ключевого слова Alias в операторе Declare (см. пример совета 2.3).
• Может быть использована разная последовательность записи передаваемых аргументов в стек. Например, во времена DOS (честно признаюсь - не знаю, как это выглядит сейчас в среде Windows), C записывал аргументы с конца списка, другие языки (Fortran, Pascal, Basic) - с начала.
• По умолчанию используются разные принципы передачи параметров - по ссылке или по значению.
• Различные принципы хранения строковых переменных. Например, в C (так же как в Fortran и Pascal) длина строки определяется нулевым байтом в ее конце, а в Basic длина записывается в явном виде в дескрипторе строки. Разумеется, нужно иметь в виду возможность использования разных кодировок символов.
• При передаче многомерных массивов следует помнить, что возможны различные варианты преобразования многомерных структур в одномерные (начиная с первого индекса или с последнего, применительно к двухмерным массивам - «по строчкам» или «по столбцам»).

С учетом всего этого можно сформулировать следующие рекомендации:

• Используйте самые простые, проверенные способы передачи аргументов в DLL-функции. Стандарты, принятые для Win API, вполне годятся в качестве образца.
• Ни в коем случае не передавайте массивы строковых переменных.
• Очень внимательно используйте передачу простых строковых переменных и многомерных массивов.
• Обязательно специальным образом проверяйте работоспособность механизма передачи аргументов в вызываемую процедуру и обратно. Напишите специальный тест для проверки передачи данных. Отдельно проверьте правильность передачи каждого аргумента. Например, если у вас есть процедура с несколькими аргументами, проверьте сначала корректность передачи каждого параметра для варианта с одним аргументом, а уж потом - для всего списка.

А что делать, если DLL-функция уже написана, например, на Фортране, но ее входной интерфейс не очень хорошо вписывается в приведенные выше стандарты VB? Здесь можно дать два совета. Первый: напишите тестовую DLL-функцию и с ее помощью постарайтесь методом проб и ошибок подобрать нужное обращение из VB-программы. Второй: напишите процедуру-переходник на том же Фортране, который бы обеспечивал простой интерфейс между VB и DLL-функцией с преобразованием простых структур данных в сложные (например, преобразовывал многомерный байтовый массив в строковый массив).

Итак: используйте DLL-функции. Но сохраняйте бдительность...

КомпьютерПресс 9"2000

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

API как средство интеграции приложений

API определяет функциональность, которую предоставляет программа (модуль , библиотека), при этом API позволяет абстрагироваться от того, как именно эта функциональность реализована.

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

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

По такому принципу построены протоколы передачи данных по Интернет . Стандартный стек протоколов (сетевая модель OSI) содержит 7 уровней (от физического уровня передачи бит до уровня протоколов приложений, подобных протоколам HTTP и IMAP). Каждый уровень пользуется функциональностью предыдущего («нижележащего») уровня передачи данных и, в свою очередь, предоставляет нужную функциональность следующему («вышележащему») уровню.

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

API библиотеки функций и классов включает в себя описание сигнатур и семантики функций .

Сигнатура функции

Иногда различают сигнатуру вызова и сигнатуру реализации функции. Сигнатура вызова обычно составляется по синтаксической конструкции вызова функции с учётом сигнатуры области видимости данной функции, имени функции, последовательности фактических типов аргументов в вызове и типе результата. В сигнатуре реализации обычно участвуют некоторые элементы из синтаксической конструкции объявления функции: спецификатор области видимости функции, её имя и последовательность формальных типов аргументов.

Например, в языке программирования C++ простая функция однозначно опознаётся компилятором по её имени и последовательности типов её аргументов, что составляет сигнатуру функции в этом языке. Если функция является методом некоторого класса, то в сигнатуре будет участвовать и имя класса.

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

С другой стороны, отличия в API различных операционных систем существенно затрудняют перенос приложений между платформами. Существуют различные методы обхода этой сложности - написание «промежуточных» API (API графических интерфейсов wxWidgets , GTK и т. п.), написание библиотек, которые отображают системные вызовы одной ОС в системные вызовы другой ОС (такие среды исполнения, как Wine , cygwin и т. п.), введение стандартов кодирования в языках программирования (например, стандартная библиотека языка C), написание интерпретируемых языков, реализуемых на разных платформах ( , python , perl , php , tcl , Java и т. д.).

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

Например: для того, чтобы увидеть в браузере строчку «Hello, world! », достаточно лишь создать HTML -документ с минимальным заголовком и простейшим телом, содержащим данную строку. Когда браузер откроет этот документ , программа-браузер передаст имя файла (или уже открытый дескриптор файла) библиотеке, обрабатывающей HTML-документы, та, в свою очередь, при помощи API операционной системы прочитает этот файл и разберётся в его устройстве, затем последовательно вызовет через API библиотеки стандартных графических примитивов операции типа «очистить окошко», «написать „Hello, world!“ выбранным шрифтом». Во время выполнения этих операций библиотека графических примитивов обратится к библиотеке оконного интерфейса с соответствующими запросами, уже эта библиотека обратится к API операционной системы, чтобы записать данные в буфер видеокарты .

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

Основными сложностями существующих многоуровневых систем API, таким образом, являются:

• Сложность портирования программного кода с одной системы API на другую (например, при смене ОС);
• Потеря функциональности при переходе с более низкого уровня на более высокий. Грубо говоря, каждый «слой» API создаётся для облегчения выполнения некоторого стандартного набора операций. Но при этом реально затрудняется, либо становится принципиально невозможным выполнение некоторых других операций, которые предоставляет более низкий уровень API.

Наиболее известные API

Операционных систем

Cистема классификации моторных масел API () была создана в 1969 году.По системе API установлены три эксплуатационные категории (три ряда) назначения и качества моторных масел:
S (Service) - состоит из категорий качества моторных масел для бензиновых двигателей, идущих в хронологическом порядке.
C (Commercial) - состоит из категорий качества и назначения масел для дизельных двигателей, идущих в хронологическом порядке.
EC (Energy Conserving) - энергосберегающие масла. Новый ряд высококачественных масел, состоящий из маловязких, легкотекущих масел, уменьшающих расход топлива по результатам тестов на бензиновых двигателях.

Для каждого нового класса присваивается дополнительная буква по алфавиту. Универсальные масла для бензиновых и для дизельных двигателей обозначаются двумя символами соответствующих категорий: первый символ является основным, а второй указывает на возможность применения этого масла для двигателя другого типа. Пример: API SM/CF.

Классы качества API для бензиновых моторов

Класс API SN – утвержден в 1 октября 2010 года.
Основное отличие API SN от предыдущих классификаций API в ограничении содержания фосфора для совместимости с современными системами нейтрализации выхлопных газов, а также комплексное энергосбережение. То есть, масла, классифицируемые по API SN, будут приблизительно соответствовать АСЕА С2, С3, С4, без поправки на высокотемпературную вязкость.

Класс API SM – утвержден 30 ноября 2004 года.
Моторные масла для современных бензиновых (многоклапанных, турбированных) двигателей. По сравнению с классом SL моторные масла, соответствующие требованиям API SM должны обладать более высокими показателями защиты от окисления и преждевременного износа деталей двигателя. Кроме того, повышены стандарты относительно свойств масла при низких температурах. Моторные масла этого класса могут быть сертифицированы по классу энергосбережения ILSAC
Моторные масла, соответствующие требованиям API SL, SM могут применяться в случаях, когда производителем автомобиля рекомендуется класс SJ или более ранние.

Класс API SL – моторные масла для двигателей машин, выпущенных после 2000 года.
В соответствии с требованиями производителей автомобилей, автомасла этого класса применяются в многоклапанных, турбированных моторах, работающих на обеднённых смесях топлива, соответствующих современным повышенным требованиям по экологии, а также энергосбережению. Автомасла, соответствующие требованиям API SL могут использоваться в случаях, когда автопроизводителем рекомендуется класс SJ или более ранние.

Класс API SJ – моторные масла для использования в бензиновых моторах начиная с 1996 года выпуска.
Данный класс описывает автомасла, которые используются в бензиновых двигателях, начиная с 1996 года выпуска. Моторные масла этого класса предназначены для использования в бензиновых моторах легковых и спортивных машин, микроавтобусов и легких грузовых машин, которые обслуживаются в соответствии с требованиями производителей автомобилей. SJ предусматривает такие же минимальные стандарты, как и SH, а также дополнительные требования к нагарообразованию и работе при низких температурах. Моторные масла, удовлетворяющие требованиям API SJ, могут применяться в тех случаях, когда производителем автомобиля рекомендуется класс SH или более ранние.

Класс API SH – моторные масла для бензиновых моторов начиная с 1994 года выпуска.
Класс принят в 1992 году для моторных масел, рекомендуемых с 1993 г. Этот класс характеризуется более высокими требованиями по сравнению с классом SG, и был разработан, как заменитель последнего, для улучшения антинагарных, противоокислительных, антиизносных свойств масел и повышенной защиты от коррозии. Моторные масла этого класса предназначены для использования в бензиновых моторах легковых машин, микроавтобусов и легких грузовых автомобилей, в соответствии с рекомендациями их производителей. Моторные масла данного класса тестировались в соответствии с требованиями Ассоциации производителей химической продукции (СМА). Моторные масла этого класса могут использоваться в тех случаях, когда производителем автомобиля рекомендуется класс SG или более ранний.

Класс API SG – моторные масла для бензиновых моторов начиная с 1989 года выпуска.
Предназначены для использования в бензиновых моторах легковых машин, микроавтобусов и легких грузовиков. Моторные масла этого класса обладают свойствами, обеспечивающими улучшенную защиту от нагара, окисления автомасла и износа мотора, в сравнении с предыдущими классами, а также содержат присадки, защищающие от ржавления и коррозии внутренних деталей двигателя. Моторные масла класса SG соответствуют требованиям к моторным маслам для дизельных моторов API CC и могут использоваться там, где рекомендуются классы SF, SE, SF/CC или же SE/CC.

Класс API SF - моторные масла для бензиновых моторов начиная с 1980 года выпуска (устаревший класс).
Эти моторные масла применялись в бензиновых моторах 1980-1989 годов выпуска, при условии наличия рекомендаций и инструкций производителя двигателя. Обеспечивают усиленную устойчивость к окислению, улучшенную защиту от износа деталей, в сравнении базовыми характеристиками автомасел SE, а также более надежную защиту от нагара, ржавления и коррозии. Моторные масла класса SF могли применяться, как заменители предыдущих классов SE, SD или SC.

Класс API SE - моторные масла бензиновых моторов выпуска с 1972 года (устаревший класс). Эти моторные масла применялись в бензиновых моторах моделей выпуска 1972-79 годов, а также некоторых моделях 1971 г. Дополнительная защита в сравнении с автомаслами SC и SD и могут использоваться, как заменители этих категорий.

Класс API SD - моторные масла для использования в бензиновых моторах с 1968 г. (устаревший класс). Автомасла этого класса использовались в бензиновых моторах легковых машин и некоторых грузовых выпуска 1968-70 годов, а также некоторых моделей 1971 г. и позднее. Улучшенная защита по сравнению с моторными маслами SC, применялись также исключительно при наличии рекомендации производителя двигателя.

Класс API SC - моторные масла для бензиновых моторов, начиная с 1964 г. выпуска (устаревший класс). Обычно применялись в моторах легковых машин и некоторых грузовиков выпуска 1964-1967 годов. Уменьшают высоко- и низкотемпературный нагар, износ, а также защищают от коррозии.

Класс API SB - моторные масла для маломощных бензиновых моторов (устаревший класс). Моторные масла 30-х годов 20-го века, обеспечивавших достаточно легкую защиту от износа и окисления, а также антикоррозийную защиту подшипников в моторах, которые эксплуатируются в легких нагрузочных режимах. Моторные масла этого класса могут применяться только, если они специально рекомендованы производителем двигателя.

Класс API SA - моторные масла для бензиновых и дизельных моторов. Устаревший класс масел для использования в старых моторах, работающих в таких условиях и режимах, при которых защита деталей с помощью присадок не нужна. Моторные масла этой класса могут применяться только, если они рекомендованы производителем двигателя.

Классы качества API для дизельных моторов

Класс API СJ-4 - действует с 1 октября 2006.
Данный класс разработан специально для тяжелонагруженных двигателей. Отвечает ключевым требованиям по нормам выбросов NOx и твердых частиц для двигателей 2007 года выпуска. На масла CJ-4 вводятся лимиты по некоторым показателям: зольность меньше чем 1,0 %, сера 0,4%, фосфор 0,12%.
Новая классификация вмещает требования более ранних категорий API CI-4 PLUS, CI-4, но несет значительные изменения требования в ответ на потребности новых двигателей, которые отвечают новым экологическим стандартам 2007 и более поздних моделей.

Класс API CI-4 (CI-4 PLUS) - новый эксплуатационный класс моторных масел для дизельных двигателей. По сравнению с API CI-4 повышены требования к удельному содержанию сажи, а также испаряемости и высокотемпературному окислению. При сертификации в данной классификации моторное масло должно тестироваться в семнадцати моторных тестах.

Класс API CI-4 - класс введен в 2002 году.
Эти моторные масла применяются в современных дизельных двигателях с различными видами впрыска и наддува. Моторное масло, соответствующее данному классу, должно содержать соответствующие моюще-диспергирующие присадки и имеет, в сравнении с классом CH-4, повышенную устойчивость к термическому окислению, а также более высокие диспергирующие свойства. Кроме того, такие автомасла обеспечивают существенное уменьшение угара моторного масла за счет снижения летучести и уменьшения испарения при рабочей температуре до 370°C, под воздействием газов. Усилены также требования относительно холодной прокачиваемости, увеличен ресурс зазоров, допусков и уплотнений мотора за счет улучшения текучести автомасла.
Класс API CI-4 введен в связи с появлением новых, более жестких требований по экологии и токсичности выхлопных газов, которые предъявляются к двигателям выпускаемым с 1 октября 2002 г.

Класс API CH-4 - действует с 1 декабря 1998 года.
Моторные масла данного класса применяются в четырехтактных дизельных двигателях, которые эксплуатируются в высокоскоростных режимах и соответствуют требованиям норм и стандартов по токсичности выхлопных газов, принятых в 1998 году.
Автомасла API CH-4 соответствуют достаточно жестким требованиям как американских, так и европейских производителей дизельных двигателей. Требования класса специально разработаны для использования в моторах, работающих на высококачественном топливе с удельным содержанием серы до 0,5%. При этом, в отличие от класса API CG-4, ресурс этих моторных масел менее чувствителен к использованию дизельного топлива с содержанием серы более 0,5%, что особенно актуально для стран Южной Америки, Азии, Африки.
Моторные масла API CH-4 соответствуют повышенным требованиям и должны содержать присадки, более эффективно предотвращающие износ клапанов и образование нагара на внутренних поверхностях. Могут применяться, как заменители моторных масел API CD, API CE, API CF-4 и API CG-4 в соответствии с рекомендациями производителя двигателя.

Класс API CG-4 - класс представлен в 1995 году.
Моторные масла этого класса рекомендуются для четырехтактных дизельных двигателей автобусов, грузовых машин и тягачей магистрального и немагистрального типа, которые эксплуатируются в режимах повышенных нагрузок, а также высокоскоростных режимах. Моторное масло API CG-4 подходит для двигателей, в которых используется высококачественное топливо с удельным содержанием серы не более 0,05%, а также в моторах, для которых не выдвигается особых требований к качеству топлива (удельное содержание серы может достигать 0,5%).
Автомасла, сертифицированные по классу API CG-4, должны более эффективно предотвращать износ внутренних деталей двигателя, образование нагара на внутренних поверхностях и поршнях, окисление, пенообразование, образование сажи (эти свойства особенно нужны для двигателей современных магистральных автобусов и тягачей).
Класс API CG-4 создан в связи с утверждением в США новых требований и стандартов по экологии и токсичности выхлопных газов (редакция 1994 года). Моторные масла этого класса могут применяться в двигателях, для которых рекомендуются классы API CD, API CE и API CF-4. Основной недостаток, ограничивающий массовое использование автомасел данного класса, например в восточной Европе и Азии, это существенная зависимость ресурса автомасла от качества используемого топлива.

Класс API CF-2 (CF-II) - автомасла, предназначенные для применения в двухтактных дизельных моторах, которые эксплуатируются в тяжелых условиях.
Класс введен в 1994 году. Моторные масла этого класса обычно используются в двухтактных дизельных двигателях, которые работают в условиях повышенной нагруженности. Масла API CF-2 должны содержать присадки, которые обеспечивают защиту повышенной эффективности от износа внутренних деталей двигателя, например цилиндров и колец. Кроме того, эти автомасла должны предотвращать накопление отложений на внутренних поверхностях мотора (улучшенная функция очистки).
Моторное масло, сертифицированное по классу API CF-2 обладает улучшенными свойствами и может использоваться вместо более ранних аналогичных масел при условии наличия рекомендации производителя.

Класс API CF-4 - моторные масла для использования в четырехтактных дизельных моторах, начиная с 1990 года выпуска.
Моторные масла данного класса могут использоваться в четырехтактных дизельных двигателях, условия эксплуатации которых связаны с высокоскоростными режимами. Для таких условий требования к качеству масел превышают возможности класса СЕ, поэтому моторные масла CF-4 могут использоваться вместо масел класса СЕ (при наличии соответствующих рекомендаций производителя двигателя).
Автомасла API CF-4 должны содержать соответствующие присадки, которые обеспечивают снижение угара автомасла, а также защиту от нагара в поршневой группе. Основное предназначение моторных масел данного класса – применение в дизельных двигателях сверхмощных тягачей и других автомобилей, которые используются для дальних поездок по автомагистралям.
Кроме того, таким моторным маслам иногда присваивается сдвоенный класс API CF-4/S. В таком случае, при условии наличия соответствующих рекомендаций производителя двигателя, эти автомасла могут применяться и в бензиновых двигателях.

Класс API CF (CF-2, CF-4) - моторные масла для дизельных двигателей с непрямым впрыском. Классы введены начиная с 1990-го и по 1994-й года. Цифра через дефис означает двух- или четырехтактный двигатель.
Класс CF описывает моторные масла рекомендованные к применению в дизельных двигателях с непрямым впрыском, а также других видах дизельных двигателей, которые работают на топливе различного качества, в том числе и с повышенным содержанием серы (например, больше 0,5% от общей массы).
Моторные масла, сертифицированные по классу CF, содержат присадки, способствующие более эффективному предотвращению отложений на поршне, износа и коррозии медных (с содержанием меди) подшипников, что имеет большое значение для двигателей этих видов, и могут прокачиваться обычным способом, а также с помощью турбонагнетателя или компрессора. Моторные масла этого класса могут использоваться там, где рекомендуется класс качества CD.

Класс API СЕ - моторные масла для использования в дизельных моторах, начиная с 1983 года выпуска (устаревший класс).
Автомасла данного класса предназначались для использования в некоторых сверхмощных турбированных моторах, характеризующихся существенно повышенной рабочей компрессией. Применение таких масел допускалось для двигателей как с низкой, так и с высокой частотой вращения вала.
Моторные масла API СЕ рекомендовались для низко- и высокооборотистых дизельных двигателей, выпущенных, начиная с 1983 года, которые эксплуатировались в режимах повышенной нагрузки. При условии наличия соответствующих рекомендаций производителя двигателя, эти автомасла могли быть использованы также в моторах, для которых рекомендовались моторные масла класса CD.

Класс API CD-II - моторные масла для использования в сверхмощных дизелях с двухтактным рпабочим циклом (устаревший класс).
Класс введен в 1985 году для использования в двухтактных дизельных моторах и является, по сути, эволюционным развитием предыдущего класса API CD. Основным предназначением использования таких автомасел являлось применение в тяжелых мощных дизельных двигателях, которые устанавливались, в основном на сельскохозяйственную технику. Моторные масла этого класса соответствуют всем рабочим стандартам предыдущего класса CD, кроме этого существенно повышены требования относительно высокоэффективной защиты двигателя от нагара и износа.

Класс API CD - моторные масла для дизельных двигателей повышенной мощности, которые использовались в сельскохозяйственной технике (устаревший класс). Класс введен в 1955 году для обычного использования в некоторых дизельных моторах, как атмосферных, так и турбированных, с увеличенной компрессией в цилиндрах, где крайне важна эффективная защита от нагара и износа. Моторные масла этого класса могли использоваться в случаях, когда производителем двигателя не выдвигались дополнительные требования к качеству топлива (включая топливо с повышенным содержанием серы).
Автомасла API CD должны были, по сравнению с предыдущими классами, обеспечивать повышенную защиту от коррозии подшипников и высокотемпературного нагара в дизельных моторах. Нередко моторные масла этого класса называли «Caterpillar серия 3», благодаря тому, что они соответствовали требованиям сертификации Superior Lubricants (Series 3), разработанной тракторной компанией Катерпиллар.

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

Класс API СВ - моторные масла для дизельных двигателей, работающих со средней нагрузкой (устаревший класс).
Класс утвержден в 1949 г., как эволюционное развитие класса СА при использовании топлива с повышенным содержанием серы без особых требований к качеству. Автомасла API СВ предназначались также для использования в моторах с наддувом, которые эксплуатировались в легком и умеренном режимах. Часто этот класс называли «Моторные масла «Приложение 1», тем самым, подчеркивая соответствие военному предписанию MIL-L-2104A Приложение 1.

Класс API СА - моторные масла для малонагруженных дизельных двигателей (устаревший класс).
Автомасла этого класса предназначены для использования в дизельных моторах, работающих в легких и умеренных режимах на качественном дизельном топливе. В соответствии с рекомендациями производителей автомобилей, могут применяться и в некоторых бензиновых моторах, которые эксплуатируются в умеренных режимах.
Класс широко использовался в 40-х и 50-х годах прошлого века и не может использоваться в современных условиях, если это не предусмотрено требованиями производителя двигателя.
Моторные масла API СА должны обладать свойствами, обеспечивающими защиту от нагара на поршневых кольцах, а также от коррозии подшипников в моторах с наддувом, для которых не предусмотрены особые требования к качеству топлива, которое используется.

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

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

Владельцы интернет-магазинов при помощи сторонних сервисов и собственных приложений имеют возможность обращаться по API к:

Информации об оформленных заказах

Доступные действия (методы) обработки информации о заказах:

1. Выбор информации о заказе по ID
2. Выбор информации о заказах по фильтру
3. Количество заказов по фильтру
4. Создание заказа
5. Удаление заказа
6. Массовое удаление заказов
7. Выбор всех доступных статусов для заказов
8. Обновление статуса заказа
9. Добавление комментария к заказу

Информации о подписчиках

1. Добавление подписчика
2. Удаление подписчика
3. Массовое удаление подписчиков
4. Выбор данных о подписчиках по фильтру
5. Количество подписчиков по фильтру

Информации о зарегистрированных пользователях

Доступные действия (методы) обработки информации о подписчиках:

1. Выбор информации о зарегистрированных пользователях по ID
2. Выбор информации обо всех зарегистрированных пользователях
3. Выбор информации обо всех данных указанных пользователем при регистрации:
   • Фамилия, имя, отчество;
   • Контактный адрес электронной почты;
   • Контактный номер телефона;
   • Указанный адрес доставки: индекс, название населенного пункта, название улицы, номер дома, номер корпуса, номер квартиры, этаж;

Обратите внимание! При регистрации, пользователь может не заполнить все указанные выше поля.

Планы по развитию API

В ближайшее время, мы планируем открыть интерфейсы для поддержки взаимодействия магазинов со сторонними приложениями и сервисами по работе с:

1. Разделами каталога.
2. Товарами.
3. Корзиной.
4. Скидками.
5. Способами доставки.
6. Способами оплаты.

Для тестирования взаимодействия с API платформы beseller создан тестовый магазин beseller-api.shop.by .

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

Перед тестированием взаимодействия с API мы рекомендуем вам:

1. оформить самостоятельно несколько заказов;
2. подписаться на рассылку;
3. посмотреть как информация об оформленных заказах и подписчиках отображается в панели администрирования магазина.

Панель управления магазином доступна по адресу: beseller-api.shop.by/manager/ . Логин и пароль при входе в панель управления аналогичны логину и паролю доступа к магазину.

Как подключиться по API к своему магазину?

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

http://адрес_вашего_сайта:8082/graphql?token=ваш_персональный_секретный_ключ

Секретный ключ вы можете получить по запросу у вашего персонального менеджера.

Функции и переменные GraphQL для работы с API платформы beseller

Как подключиться к API с использованием языка программирования PHP

Для удобства работы с API платформы beseller вы можете воспользоваться:

1. Классами разработанными нами под PHP.
   1. GraphqlClient - осуществляет прием и передачу данных на сервер;
   2. GraphQlHelper - содержит в себе реализованные query и mutation API;
2. Примерами использования классов для осуществления выборок и изменений в базе данных интернет-магазина.

Настройка локального окружения

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

В качестве локального окружения используется GraphiQL Feen , это расширение для браузера Google Chrome которое позволяет формировать запросы к API.

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

Откройте приложение GraphiQL Feen и перейти на вкладку «SERVERS», выберите метод отправки POST, после чего укажите url-адрес доступа к API.

В качестве тестового url необходимо использовать следующий адрес:

Локальное окружение настроено, можно формировать запросы к API. Для этого необходимо открыть вкладку «QUERIES»

Формирование запроса к API beseller при помощи GraphiQL Feen и полученный ответ

Пояснения к скриншоту:

1. Сохраненные запросы
2. Поле для ввода запросов
3. Поле ввода переменных
4. Полученный ответ
5. Кнопка запуска

Пример запроса на получение списка оформленных заказов за указанный промежуток времени

query ($first:Int, $offset:Int, $filter: OrdersFilterType){
orders(first:$first, offset:$offset, filter:$filter){
comment
status{
id
description
name
}
create_date
update_date
total {
suffix
value
}
payment {
name
description
cost {
suffix
value
}
}
delivery {
name
description
cost {
suffix
value
}
}
currencies {
bank_code
course
suffix
}
user_data {
name
description
value
}
}
}

Указание промежутка времени для выборки данных об оформленных заказах

{
"filter": {
"date_after": "2017-11-16T00:00:01Z",
"date_before": "2017-11-23T00:00:01Z"
}
}

Пример ответа от API

{{
"data": {
"orders": [
{
"comment": "Culpa officiis vel ut.",
"create_date": "2017-11-22 16:23:28",
"currencies": [
{
"bank_code": "BYN",
"course": 10000,
"suffix": "руб."
}
],
"delivery": {
"cost": [
{
"suffix": "руб.",
"value": 0
}
],
"description": "Курьер",
"name": "custom"
},
"payment": {
"cost": [
{
"suffix": "руб.",
"value": 0
}
],
"description": "Пластиковые карты",
"name": "custom"
},
"status": {
"description": "Новый",
"id": 1,
"name": "new"
},
"total": [
{
"suffix": "руб.",
"value": 4450
}
],
"update_date": "2017-11-22 16:23:28",
"user_data": [
{
"description": "Адрес e-mail",
"name": "email",
"value": "[email protected]"
},
{
"description": "Телефон",
"name": "phone",
"value": "784.392.3949 x69329"
},
{
"description": "Адрес",
"name": "registration",
"value": "607 Erik Station Suite 057\nReynaberg, WY 83542-0037"
},
{
"description": "Комментарий",
"name": "comment",
"value": "Id nam illo optio."
},
{
"description": "ФИО",
"name": "fio",
"value": "Jordi Mann MD"
}
]
}

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

API (Application Programming Interface) - набор готовых классов, процедур, функций, структур и констант, предоставляемых приложением (библиотекой, сервисом) для использования во внешних программных продуктах (Wikipedia).

Своими словами, API предоставляет нам возможность использовать чужие наработки в своих целях. Впервые я столкнулся с API на примере Windows API. Это набор функций, которые может использовать любое приложение, запущенное на данной ОС. К примеру, оно может использовать стандартные функции для отрисовки интерфейса.

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

На сайте https://dev.hh.ru/ (а точнее, https://github.com/hhru/api/blob/master/docs/general.md) вы можете найти описание того, как клиенты и сервисы HeadHunter API взаимодействуют между собой. Например, цитата с сайта:

• Всё API работает по протоколу HTTPS.
• Авторизация осуществляется по протоколу OAuth2.
• Все данные доступны только в формате JSON.
• Базовый URL — https://api.hh.ru/
• Даты форматируются в соответствии с ISO 8601 : YYYY-MM-DDThh:mm:ss±hhmm

Вы можете почитать HH API - это хороший пример пользовательской документации.

Форматы передачи данных

Существует множество форматов данных, с помощью которых пользователи взаимодействуют с API. Например, широко известный XML. Или JSON - легковесный и несложный формат, который выглядит как:

{ "id": "0001", "type": "donut", "name": "Cake", "image": { "url": "images/0001.jpg", "width": 200, "height": 200 } } По ссылкам ниже вы можете посмотреть ответы, приходящие от MediaWikiAPI , в разных форматах:

JSON: https://en.wikipedia.org/w/api.php?action=query&titles=Albert%20Einstein&prop=info&format=jsonfm
XML: https://en.wikipedia.org/w/api.php?action=query&titles=Albert%20Einstein&prop=info&format=xmlfm
PHP: https://en.wikipedia.org/w/api.php?action=query&titles=Albert%20Einstein&prop=info&format=php (осторожно, произойдет с качивание файла)

HTTP глаголы

Обычно при обращении к веб API используют ся запросы HTTP. Поэтому нужно хотя бы коротко сказать о стандартных методах, которые могут содержаться в HTTP запросе. Эти методы также называют HTTP глаголами:

• GET. Наверное, самый популярный тип запроса. Используется для получения или чтения данных.
• PUT. Обычно и спользуется для обновления ресурса.
• POST. Обычно используется для создания нового ресурса.
• DELETE. Удаляет данные.
• И другие

Если мы хотим получить информацию о ресурсе, URI которого http://www.example.com/customers/12345 , мы можем послать запрос:
GET http://www.example.com/customers/12345

Если мы хотим обновить ресурс - мы можем послать PUT-запрос:
PUT http://www.example.com/customers/12345/orders/98765

Обычные GET запросы способен посылать веб-браузер. Для посылки других типов запросов могут потребоваться скриптовые языки или специальные инструменты (об этом будет ниже).

О HTTP методах можно подробнее почитать на W iki .

HTTP к оды ответов

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

Наиболее известные коды - 4xx (проблемы на стороне клиента) и 5xx (проблемы на стороне сервера). О том, какие коды возвращать в той или иной ситуации, решают разработчики самих API. Например, API сайта Одноклассники возвращает коды, описание которых можно найти на странице https://apiok.ru/wiki/pages/viewpage.action?pageId=77824003 .

Кроме того, советую послушать песню Реквест-респонс - просто и понятно о кодах, возвращаемых в HTTP запросах (осторожно, репчик:)).

REST API

REST API - э то идеология построения API, которая расшифровывается как Representational State Transfer API. Она основывается на следующих принципах , сформулированных ее создателем, Роем Филдингом :

1. Клиент-серверная архитектура
2. Stateless сервер
3. Кешируемость
4. Многослойная структура
5. Единый интерфейс
6. Код по требованию

Не буду углубляться в детали, желающим почитать по теме могу посоветовать