Управление работой подсистемы P-Invoke осуществляется при помощи методов пространства имен System.Runtime. InteropServices. Из-за этого нередко возникает путаница, поскольку не всегда понятно, какие объекты и методы этого пространства имен относятся к COM Interop, какие — к P-Invoke, а какие применимы в обеих областях. Ситуация усложняется тем, что атрибуты, управляющие передачей параметров при вызове функций Win32 API, также управляют передачей параметров при вызове методов СОМ!

Поэтому передача параметров не рассматривалась в части этой главы, посвященной СОМ, — они ничем не отличаются от параметров, передаваемых при вызове функций Win32 API. А поскольку COM Interop весьма разумно действует по умолчанию, приведенный ниже материал с большей вероятностью пригодится при вызове функций Win32 API, нежели в COM Interop.

Становится понятно, почему мы ничего не теряем с исчезновением VarPtr, StrPtr и Obj Ptr. Все «хакерские» приемы, основанные на использовании этих функций, значительно проще и надежнее реализуются средствами P-Invoke. Подумайте: все объекты .NET, использующие возможности операционной системы, от форм Windows до Winsock, должны использовать P-Invoke. Неудивительно, что P-Invoke не только справляется со всеми задачами, связанными с API, но и весьма стабильно работает.

Конечно, из этого вовсе не следует, что в P-Invoke легко разобраться.

Атрибуты передачи параметров

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

•  MarshalAs. Атрибут указывает, как CLR следует передавать данные (например, должна ли строка передаваться в виде указателя на строку, завершенную нуль-символом, или в строковом формате OLE BSTR).
• UnmanagedType. Используется в сочетании с атрибутом MarshalAs для описания передачи параметров.
•  Marshal. Объект содержит большое количество общих методов для выполнения исключительно разнообразных задач, связанных с управлением памятью. Например, вы можете выделить блок неуправляемый памяти и вручную передавать данные в память с использованием атрибутов передачи параметров.
•  GCHandle. Атрибут позволяет зафиксировать местонахождение объекта в управляемой памяти и получить указатель, по которому можно обращаться из неуправляемой памяти. На первый взгляд такая возможность выглядит весьма заманчиво, но на практике почти не используется.

Осваиваем P-Invoke

В процессе работы над этой главой я столкнулся с двумя проблемами.

1. Поскольку в Win32 API входит более 9000 функций, я не смогу ни предвидеть все нюансы каждой функции, ни изложить этот материал в ограниченном пространстве.
2.  Мне неизвестна ваша квалификация. Если бы я написал эту главу для новичков в области Win32 API, только на описание базовых концепций потребовалось бы не менее сотни страниц.

Итак, я буду исходить из двух предположений. Во-первых, у вас уже имеется некоторый опыт вызова функций API в Visual Basic — достаточный, чтобы я мог сказать «как в VB6» и быть уверенным в том, что в дальнейшем вы разберетесь. Во-вторых, вы готовы читать документацию и заниматься самостоятельными исследованиями¹.

Руководствуясь этими предположениями, я сначала покажу, как узнать точные значения параметров, переданные при вызове функции API. Я сам пользовался этим приемом, выясняя, как различные атрибуты влияют на передачу параметров.

¹А если не готовы, я могу провести консультации в частном порядке, только это обойдется недешево.

Проект VBInterface

Откройте решение из каталога VBInterface (не обращайте внимания на файлы .срр). В результате открываются два проекта: VBInterface и VBInterfaceTest.

Программа VB .NET VBInterfaceTest демонстрирует вызов функций DLL с разными параметрами. Программа VBInterface представляет собой библиотеку DLL, экспортирующую функции. Библиотека написана на C++ и состоит из неуправляемого кода.

Оба проекта загружаются одновременно; проект VBInterfaceTest выбирается в качестве стартового. Для совместной отладки проектов остается лишь вызвать диалоговое окно свойств проекта VBInterfaceTest, выбрать команду Configuration Properties> Debugging на левой панели и убедиться в том, что флажок Unmanaged Code Debugging установлен.

Начнем с простого примера.

Функция ReceivesShortDLt определяется в файле VBInterface.срр следующим образом:

STDAPI_(short) ReceivesShort (short x)

{

_itoa(x, tbuf, 10); /* Разместить во временном буфере */ MessageBox(GetFocus(),(LP5TR)tbuf,(LPSTR)"ReceivesShort", MB_OK); return(x);

}

Функция выводит окно сообщения с полученной 16-разрядной величиной и возвращает это же значение. Объявление в файле VBInterface выглядит так:

Public Denction ReceivesShort Lib _ "..\..\VBInterface\Debug\VBInterface.dll" (ByVal s As Short) As Short

Пример вызова в функции Numbers программы VBInterfaceTest:

i = ReceivesShort(4) ; Console.WriteLine(i)

При выполнении этого кода число 4 будет выведено в окне сообщения и на консоли.

Попробуйте установить точку прерывания в одной из этих команд, а затем продолжить выполнение в пошаговом режиме. Вы увидите, что управление передается прямо в программу C++. Находясь в программе C++, вы сможете просмотреть значения полученных параметров.

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

Секреты передачи параметров

На простом уровне передача большинства типов данных обходится без проблем. Если вы знакомы с вызовом функций API в VB6, единственное, о чем следует помнить (не считая особого подхода к структурам, о котором будет сказано ниже), — это замена типа Long типом Integer. В табл. 15.1 перечислены основные типы параметров Win32 API (согласно документации Win32 API) и эквивалентные определения в команде De

Таблица 15.1. Передача простых параметров функциям API

Внимательнее с типом Long!

Как я уже говорил, самой распространенной ошибкой программистов VB .NET при работе с Win32 API будет использование 64-разрядного типа Long для 32-разрядных параметров. Проект VBInterface показывает, что происходит при ошибочной передаче данных типа Long. Файл VBInterface.cpp:

STDAPI_(_int64) ReceivesLong(_int64 у) {

DumpValues((LPVOID)&y, 8);

return(y+0xl000200030004000); }

Модуль Modulel.vb проекта VBInterfaceTest:

Public Denction ReceivesLong Lib _ "..\..\VBInterface\Debug\VBInterface.dll" (ByVal a As Long) As Long

1 = ReceivesLong(4) ;

Console.WriteLine(Hex$(l))

Результат в окне сообщения: 00 40 00 30 00 20 00 10.

Возвращаемое значение: 2000400060008000.

Данные в окне сообщения выглядят несколько странно. Вывод шестнадцатеричного дампа памяти осуществляется функцией DumpValues. В PC память организована таким образом, что младшая часть числового значения расположена по младшему адресу памяти. Таким образом, байтовая последовательность 00 40 соответствует числу &Н4000.

Так или иначе, данный пример еще раз подчеркивает необходимость использования типа Integer вместо Long в объявлениях API. Конечно, при передаче типа .NET Long (64-разрядного) функции Win32 API, рассчитывающей на получение типа long C++ (32-разрядный), может произойти серьезная ошибка.

Передача строк

При вызове функций Win32 API, получающих строковые параметры, строки практически всегда объявляются в виде ByVal As String.

Вспомните, что говорилось в главе 9 о возможности модификации объектов, переданных по значению, и о неизменности строк. VB .NET идет на небольшое жульничество. Хотя в объявлении указано ключевое слово ByVal, VB .NET присваивает переменной типа String, переданной в качестве параметра, новое значение, совпадающее со значением строки после возврата из функции.

Иначе говоря, перед нами один из тех случаев, когда синтаксис VB .NET совместим с синтаксисом VB6. Мне это кажется довольно странным, поскольку в VB6 этот синтаксис выглядел нелогично. Странно, что этот дефект не был исправлен в процессе чистки языка. Впрочем, на передачу строковых параметров все равно можно повлиять при помощи атрибутов.

Начнем с рассмотрения функций DLL, не изменяющих строк.

Функции ReceivesANSIString и ReceivesUnicodeString предназначены для получения и вывода строк в кодировках ANSI и Unicode. Функция ReceivesAutoString выводит дамп полученного буфера и наглядно показывает, какой формат используется в конкретной операционной системе.

/* Используется для большинства функций API. VBcalls.

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

*/ STDAPI_(VOID) ReceivesANSIString(LPSTR tptr)

{

MessageBox(GetFocus(), (LPSTR)tptr, (LPSTR)"ReceivesANSIString", MB_OK);

}

STDAPI_(VOID) ReceivesUnicodeString(LPWSTR tptr)

{

MessageBoxW(GetFocus(), tptr, L"ReceivesUnicodeString", MB_OK); }

STDAPI_(VOID) ReceivesAutoString(LPSTR tptr, int count) 

{

DumpValues(tptr, count); 

}

В листинге 15.8 приведены объявления и примеры вызовов этих функций в проекте VBInterfaceTest.

Листинг 15.8. Примеры использования строковых функций в проекте VBInterfaceTest

Public Deub ReceivesANSIString Lib _

"..\..\VBInterface\Debug\VBInterface.dU" (ByVal s As String)

Public De Sub ReceivesUnicodeString Lib _

"..\..\VBInterface\OebugWBInterface.dll" (ByVal s As String)

Public Deb ReceivesAutoString Lib _

"..\..\VBInterface\Debug\VBInterface.dll" (ByVal s As String,

ByVal chars As Integer)

Public DeeivesNoInfoString Lib _

"..\..\VBInterface\Debug\VBInterface.dll"

Alias "ReceivesAutoString" (ByVal s As String, ByVal chars As Integer)

Dim s As String = "Test string"

Dim s2 As String

Console.WriteLine ("Strings examples")

ReceivesANSIString (s)

ReceivesUnicodeString (s)

s2 = s

ReceivesAutoString(s, Len(s))

If Not s2 Is s Then

Console.WriteLlne _

("s and s2 are no longer the same after after ReceivesAutoString") 

End If ReceivesNoInfoString(s, Len(s))

Проанализируем полученный результат.

Функция ReceivesAnsiString правильно получает и выводит строку «Test String». To же самое можно сказать и о функции ReceivesUnicodeString. Это доказывает, что атрибуты Ansi и Unicode обеспечивают передачу строковых параметров в заданном формате.

Функция ReceivesAutoString выводит последовательность 54 00 65 00 73 00 74 00 20 00 73. Несомненно, перед нами строка Unicode (поскольку программа выполнялась в Windows 2000, а эта система использует кодировку Unicode). Последовательность усечена, поскольку количество байт вдвое больше количества символов в строке, но и приведенный фрагмент однозначно показывает, что перед нами строка Unicode.

Любопытная подробность: хотя строка передавалась с ключевым словом ByVal, на экране появляется сообщение о том, что строка изменилась. В данном случае поведение VB .NET не соответствует общепринятой трактовке атрибута ByVal.

При отсутствии заданной кодировки выводится последовательность 54 65 73 74 20 73 74 72 69 6е 67. Это наглядно доказывает, что по умолчанию в VB .NET используется кодировка ANSI (и это вполне логично для сохранения совместимости с VB6). Тем не менее атрибут кодировки всегда следует задавать явно.

В следующем примере (листинг 15.9) функция модифицирует переданные строки. Приведенный фрагмент взят из файла VBInterface.cpp.

Листинг 15.9. Примеры использования строковых функций в проекте VBInterfaceTest (продолжение)

/* Модификация строки (при условии, что программа не выходит

 за границы выделенного буфера */

5TDAPI_(VOID) ChangesStringA(LPSTR tptr) 

{

if Ctptr) *tptr = 'A' ; 

}

STDAPI_(VOID) ChangesStringW(LPWSTR tptr)

 {

if(*tptr) «tptr = 'W;

 }

STDAPI_(VOID) ChangesByRefStringW(LPWSTR *ptr) 

{

lstrcpyW(*ptr, L"New String"); 

}

STDAPI_(VOID) ChangesByRefStringACLPSTR »ptr) 

{ 

lstrcpyA(*ptr, "New String");

}

STDAPI_(VOID) ChangesBSTRString(BSTR *sptr)

 {

if(lsptr) return; 

// Условие никогда не выполняется (перестраховка)

if(*sptr) SysFreeString(*sptr);

*sptr = SysAllocString(L"Any Length Ok");

 }

/* Возвращение строки при вызове функции DLL. */

STDAPI_(BSTR) ReturnsVBStringO

{

return(SysAllocString(L"Here's a return string")); 

}

В проекте VBInterfaceTest используется следующий код:

Public De ChangesString Lib _ "..\..\VBInterface\Debug\VBInterface.dll" (ByVal s As String) 

Public De ChangesByRefString Lib _ "..\..\VBInterface\Debug\VBInterface.dll" (ByRef s As String) 

Public DeSub ChangesBSTRString Lib _ "..\..\VBInterface\Debug\VBInterface.dll" (<MarshalAs(UnmanagedType.BStr)> ByRef s As String) 

Public DeFunction ReturnsVBString Lib _ "..\..\VBInterface\Debug\VBInterface.dll" () As <MarshalAs(UnmanagedType.BStr)> 

String

s2 = s

ChangesString (s) If Not s2 Is s Then

Console.WriteLine ("s and s2 are no longer the same after ChangesString") End If

Console.WriteLine ("Changed String; " & s)

 ChangesByRefString (s)

Console.WriteLine ("Changed ByRef String: " & s)

 ChangesBSTRString (s)

Console.WriteLine ("Changed BSTR String: " & s) 

s = ReturnsVBString() 

Console.WriteLine ("Returned String: " & s)

Результат выглядит следующим образом:

s and s2 are no longer the same after ChangesString 

ChangedString: West string

 Changed ByRef String: New String 

Changed BSTR String: Any Length Ok 

Returned String: Here's a return string

Функция ChangesStrl ng изменяет один символ в строке, переданной по значению. Как и в VB6, необходимо действовать очень осторожно, чтобы не изменить данные за концом строки. Если длина строки, заданная при инициализации, недостаточна для хранения возвращаемых данных, вызов почти наверняка приведет к исключению защиты памяти.

У функции ChangesString есть одна любопытная особенность: она наглядно показывает, как работает атрибут Auto при объявлении функции. В объявлении ChangesString не указан псевдоним ChangesStringA или ChangesStringW, но результат доказывает, что в DLL была найдена точка входа ChangesStringW (предполагается, что программа работает в операционной системе, использующей кодировку Unicode).

При передаче строки с ключевым словом ByRef функция получает указатель на переменную, содержащую указатель на строковый буфер. Не пытайтесь присваивать значение этой переменной, поскольку это лишь приведет к сбою в программе. Правило о предварительном выделении буфера достаточного размера действует и в этом случае. Данный тип параметра (LPSTR) используется лишь небольшим подмножеством функций Win32 API. В таких случаях можно объявить параметр ByRef As Integer, а затем при помощи объекта Marshal получить строку но указателю, полученному при вызове функции API¹. Кстати, в этом отношении VB .NET отличается от VB6, где для параметров ByRef As String передается указатель на BSTR (строковый тип OLE).

¹Методы Marshal.PtrToStringAnsi, Marshal.PtrToStringAuto и Marshal.PtrToStringUni позволяют получить объект .NET типа S t M n g по указателю на блок неуправляемой памяти. Эти методы работают аналогично методу Marshal. PtrToStructure, встречающемуся ниже в этой главе.

Тип BSTR может передаваться при вызове функций API, хотя в общих функциях Win32 API он не используется (только в функциях подсистемы OLE). Эта возможность продемонстрирована в функциях ChangesBStrString и ReturnsVBString. Обратите внимание на атрибут MarshalAs(UnmanagedType.BSTR): он сообщает CLR о том, что переданные строки относятся к типу B5TR. Преимущество типа BSTR заключается в том, что он позволяет изменять длину строки или определить возвращаемую строку с произвольной длиной.

Хотя тип BSTR не применяется при вызовах функций Win32 API, он широко используется во внутренних операциях COM Interop.

Передача массивов

С передачей массивов нередко возникают трудности. В листинге 15.10 приведен фрагмент файла VBInterface.cpp. Функция ReceivesShortArray получает указатель на short (первое число в последовательности), а функция Recei vesShortRef Array получает указатель на переменную, содержащую адрес массива. Обе функции увеличивают значения первых двух элементов массива (показывая, что данные были скопированы в исходный массив). Функция ReturnsSafeArray показывает, как функция DLL может полностью переопределить переданный массив.

Листинг 15.10. Операции с массивами в программе C++

/* Целочисленный массив целых чисел - следите за тем,

чтобы не нарушить границы массива!

Обратите внимание на специальную схему передачи параметров

в примере VB - для строк она ие подходит.

 */

5TDAPI_(VOID) ReceivesShortArray(short FAR *iptr)

 { 

wsprintf((LPSTR)tbuf, (LPSTR)"lst 4 entries are %d %d %d %d",

*(iptr), *(iptr+l), *(iptr+2), *(iptr+3));

MessageBox(GetFocus() , (LPSTR)tbuf, (LPSTR)"ReceivesShortArray", MB_OK);

 (*iptr)++; // Увеличить элемент массива, чтобы проверить

 // передачу адресом и узнать, выполняется ли 

// операция с временной копией. 

(*(iptr+l))++; 

}

short newArrayBuffer[4] = { 5, 4, 3, 2};

STDAPI_(VOID) ReceivesShortRefArray(snort FAR **piptr)

 {

short *iptr;

iptr = *piptr;

wsprintf((LPSTR)tbuf, (LPSTR)"lst 4 entries are %d %d %d %d",

*(iptr), *(iptr+l), *(iptr+2), *(iptr+3));

MessageBox(GetFocus(), (LPSTR)tbuf, (LPSTR)"ReceivesShortArray", MB_OK);

 (*iptr)++; // Увеличить элемент массива, чтобы проверить

// передачу по ссылке и узнать, выполняется ли

 // операция с временной копией. 

(*(iptr+l))++; *piptr = newArrayBuffer; }

STDAPI_(VOID) ReturnsSafeArray(SAFEARRAY **psa) 

{

short *pdata;

pdata = (short *)

((*psa)->pvData);

wsprintf((LPSTR)tbuf, (LPSTR)"Array of %d dimensions, %ld bytes per elementXn First int entry is %d", (*psa)->cDims, (*psa)->cbElements, *pdata);

MessageBox(GetFocus(), (LPSTR)tbuf, (LPSTR)"ReturnsArray", MB_OK);

SAFEARRAYBOUND bounds[1];

long 1;

bounds[0].ILbound = 0;

bounds[0].cElements = 4;

*psa = SafeArrayCreate(VT_I2, 1, bounds);

short storeval;

ford = 0; 1<4; 1++)

 { 

storeval = (short)l * 5;

 SafeArrayPutElement(*psa, &1, Sstoreval); 

} 

}

Начнем с ReceivesShortArray. Эта функция ожидает получить указатель на массив 16-разрядных чисел типа Short. При вызове используются два разных варианта объявления. В одном случае передается первый элемент массива, а во втором — весь массив по значению (листинг 15.11).

Листинг 15.11. Передача массивов в проекте VBInterfaceTest

Public DeivesShortArray1 Lib _

"..\..\VBInterface\Debug\VBInterface.dll" Alias_

"ReceivesShortArray" (ByRef i As Short) 

Public DeivesShortArray2 Lib _

"..\..\VBInterface\Debug\VBInterface.dll" Alias

"ReceivesShortArray" (ByVal i() As Short)

Dim i() As Short = {1, 2, 3, 4}

Dim x As Integer

ReceivesShortArrayl (i(0)) 

For x = 0 To 3 

Console.Write (Str(i(x)) & ", ")

Next x

console.WriteLine()

ReceivesShortArray2 (1)

 For x = 0 To 3

Console.Write (Strd(x)) & ", ")

 Next x console. 

WriteLine()

При первом вызове Recei vesShortArray в окне сообщения выводится последовательность «1, 2, 3, 4». Следовательно, хотя при вызове указывается только первый элемент массива, VB .NET фактически передает в неуправляемую память весь массив. Вероятно, эта возможность была добавлена в VB .NET для поддержки способа, часто используемого программистами VB6 при передаче массивов функциям API. При возвращении из функции выводится последовательность «2, 3,3,4», из чего можно сделать вывод, что измененные элементы массива успешно возвращены в массив .NET.

То же самое происходит и при передаче по значению, из чего можно сделать вывод об идентичности этих вызовов.

Функция ReceivesShortRefArray правильно получает массив (с элементами 3, 4, 3, 4), но по возвращении оказывается, что верхняя граница массива равна 0! Что произошло? Interop не может сделать обоснованных предположений относительно длины модифицированного массива, поэтому она копирует только первый элемент! Впрочем, как показано ниже, в программе можно определить массив фиксированной длины, чтобы система знала размер массива при возвращении из функции.

Public DeivesShortRefArray Lib "..\..\VBInterface\Debug\VBInterface.dll" (ByRef 1() As Short)

ReceivesShortRefArray (i)

Console.WriteLine ("Array bound is now: " & UBound(i))

console.WriteLine()

Функция ReturnsSafeArray демонстрирует передачу массива по ссылке в виде типа OLE SAFE ARRAY.

Public DernsSafeArray Lib ",.\..\VBInterface\Debug\VBInterface.dll" (<MarshalAs(UnmanagedType.SafeArray)> ByRef i() As Short)

ReturnsSafeArray (i) For x = 0 To UBound(i)

Console.Write (Str(i(x)) & ". ") Next console.WriteLine()

Тип SAPEARRAY, как и упоминавшийся выше тип BSTR, не применяется при вызове функций Win32 API (возможно, кроме функций OLE API), но широко используется во внутренней работе COM Interop.

Структуры

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

Тем не менее задача усложняется рядом обстоятельств.

•  Структуры .NET не похожи на те структуры, к которым вы привыкли. Например, поля в них могут храниться в памяти в произвольном порядке.
•  В .NET не поддерживаются строки фиксированной длины — неотъемлемая часть многих структур Win32 API.
•  В .NET не поддерживаются массивы фиксированной длины, также задействованные по многих структурах Win32 API.

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

Расположение полей структуры в памяти

Прежде всего, следует запомнить, что все функции API рассчитывают на определенный порядок следования полей структуры в памяти. Впрочем, это и так понятно. Тем не менее функции API не всегда подчиняются одним и тем же правилам выравнивания. В большинстве функций используется упаковка по границам байтов, то есть все поля следуют непосредственно друг за другом без заполнителей. В VB6 структуры передаются с естественным выравниванием, то есть каждое поле выравнивается по границе, кратной его размеру. Байтовые поля могут находиться где угодно, 16-разрядные поля выравниваются по границам четных байтов, а 32-разрядные поля выравниваются по границе 4 байт. Рассмотрим следующую структуру C++:

typedef struct usertypestruct {

BYTE a; // Соответствует типу VB Byte

short b;

long c;

BYTE d[4];

char e[16];

 } usertype;

При естественном выравнивании ANSI-версия этой структуры представляет собой следующую последовательность байтов (буквы обозначают байты соответствующих полей, а нули — заполнители, вставленные компилятором): 

a0bbccccddddeeeeeeeeeeeeeeee=28 байт

При выравнивании по границе байтов массив выглядит так:

 abbccccddddeeeeeeeeeeeeeeee=27 байт

В проекте VBInterface компилятор настроен на выравнивание по границе байтов, поэтому в данном случае VB6 не сможет правильно передать структуру функции DLL!¹К счастью, в большинстве функции API поддерживается явное включение заполнителей. Даже несмотря на то, что такие функции используют упаковку по границе байтов, они правильно работают с VB6.

¹ В таких случаях помогает компонент для упаковки/распаковки пользовательских типов, входящий в пакет Dcsaware SpyWorks.

В VB .NET тип упаковки полей определяется атрибутом StructLayout (листинг 15.12).

Листинг 15.12. Атрибут StructLayout

<Structl_ayout (LayoutKind. Sequential, Pack:=l)> Public Structure GoodStruct Public A As Byte

 Public В As Short 

Public С As Integer

<MarshalAs(UnmanagedType.ByValArray , SizeConst:=4)> Public D() As Byte <MarshalAs(UnmanagedType.ByValTStr, SizeConst:=16)> Public E As String

Public Sub InitStruct()

A = 1

В = 2

С = 3

ReDim D(3)

D(0) = 4

D(l) = 5

D(2) = 6

0(3) = 7

E = "16 char string " ' С нуль-символом 

End Sub

 End Structure

Практически всегда используется последовательное расположение полей в структурах (LayoutKI nd . Sequent! al) и упаковка по границе байтов. Более того, атрибут StructLayout позволяет задать расположение полей в памяти с указанием точного смещения каждого поля от начала структуры. Проблемы с выравниванием уходят в прошлое!

Байтовые массивы и строки в .NET определяются в виде обычных массивов и объектов String. Массив должен инициализироваться с правильной длиной в методе Structure (для структур конструктор по умолчанию не переопределяется, поэтому не забудьте вызвать этот метод перед использованием структуры). Массив передается как при передаче по ссылке (как было показано из приведенного выше примера с массивами, именно этот способ передачи массивов функциям API является правильным). Указание размера массива обеспечивает возможность передачи массива фиксированного размера в обоих направлениях.

Для строки указан тип передачи ByValTStr — тип TSTR относится к строке, тип которой зависит от используемой операционной системы. Другими словами, в Unicode-системах строка представляется 32 байтами в кодировке Unicode. Большинство строк в структурах, используемых функциями API, фактически являются строками TSTR, тип которых зависит от использованной точки входа. Применение типа ByValTStr в структурах фактически эквивалентно использованию атрибута Auto в команде De

Определение функции ReceivesUserType для точки входа ANSI выглядит следующим образом:

/* Передача по ссылке */

"STDAPI_(VOID) ReceivesUserType(usertype FAR *u)

{

DumpValues(u, 30);

 wsprintf((LPSTR)tbuf,

(LPSTR)"usertype contains %d %d %d (%d %d %d %d) %s".

u->a, u->b, u->c, u->d[0]. u->d[l], u->d[2], u->d[3], u->e);

 MessageBox(GetFocus(), (LPSTR)tbuf, (LPSTR)"ReceivesUserTypel", MB_OK); if(u->c == 3) 

{

lstrcpy(u->e, "New Data"); v u->d[0] = 99;

 } 

}

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

 01 02 00 03 00 00 00 04 05 06 07 20 36 20 63 68 61 72 20 73 74 72 69 6е 67 20

Перед нами структура в формате с упаковкой полей по границе байтов.

Функция DLL копирует текст «New Data» в строковое поле. Вывод строки после возвращения из функции показывает, что модифицированные данные были успешно переданы в структуру. Также передается и измененное содержимое массива, о чем свидетельствует значение 99 в консольном окне.

 

Нетривиальные вызовы функций Win32 API

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

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

Получение информации о соединениях удаленного доступа при помощи функции API RasNumEntries

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

ПРИМЕЧАНИЕ

Для понимания примеров RasEntries и RasGetEntry, описанных в этом разделе, требуется хорошее знание общих концепций программирования (указатели, расположение данных в памяти и т. д.) и нетривиальных приемов использования API в VB6. Я привожу эти примеры для опытных читателей, хотя разобраться в них полностью смогут далеко не все.

Структура RASENTRYNAME определяется следующим образом¹:

typedef struct _RASENTRYNAME {

DWORD dwSize;

TCHAR szEntryName[RAS_MaxEntryName + 1]; 

} RASENTRYNAME;

Значение RAS_MaxEntryName равно 256.

В листинге 15.13 приведено определение структуры RASENTRYNAME из проекта RasEntries.

¹ Для простоты из определения исключены новые поля, появившиеся в Windows 2000. Версия структуры определяется значением поля dwSi ze.

Листинг 15.13. Структура RASENTRYNAME

'Приложение RasEntries

' Copyright ©2091 by Oesaware Inc. All Rights Reserved

Imports System.Runtime.InteropServices Module Modulel

' 256 символов в szEntryName, буфер на 257 символов

<StructLayout(LayoutK1nd.Sequential. Pack:=4, CharSet:=Charset.Auto)> _ Structure RASENTRYNAME

 Public dwSize As Integer

<MarshalAs(UnmanagedType.ByValTStr, sizeConst:=257)>

 Public szEntryName As String Public

 Sub Init()

dwSize = Marshal.SizeOf(Me) 

End Sub

 End Structure

Если заглянуть в заголовочный файл rasapi.h, вы найдете в нем строку #include <pshpack4.h> — признак того, что поля этой структуры выравниваются по границе 4 байт вместо ¹.

В листинге 15.13 также продемонстрировано использование автоматического выбора кодировки для структур. Атрибут Charset.Auto аналогичен атрибуту Auto команды Deно относится к строкам внутри структур.

Поле szEntryName передается в виде строки фиксированной длины, состоящей из 257 символов.

Поле dwSize должно содержать размер структуры в байтах. Хотя его значение можно вычислить вручную, объект Marshal содержит общий метод SizeOf, возвращающий размер структуры при передаче в неуправляемую память. Этот метод значительно надежнее функции VB6 LenB, и с его помощью можно проверять правильность задания атрибутов полей структуры. Инициализировать поле szEntryName не обязательно, поскольку атрибут MarshalAs определяет размер строки и обеспечивает передачу данных нужной длины.

Объявление функции API RasEnumEntries в документации MSDN выглядит так:

DWORD RasEnumEntries (

LPCTSTR reserved, // Зарезервировано, должно быть равно NULL

 LPTCSTR IpszPhonebook, // Указатель на полное имя файла

// телефонной книги 

LPRASENTRYNAME Iprasentryname,

// Буфер, заполняемый данными, 

// из телефонной книги.

LPDWORD Ipcb, // Размер буфера в байтах

 LPDWORD IpcEntries // Количество структур, записанных в буфер

 ):

Мы воспользуемся следующей командой De

Public Dection RasEnumEntries Lib _ "rasapi32.dll" (ByVal reserved As Integer, ByVal IpszPhoneBook As String, ByVal rasentries As IntPtr, ByRef Ipcb As Integer, ByRef IpcEntries As Integer) As Integer

В параметре rasentries передается адрес блока неуправляемой памяти. Ниже показано, .как создать этот блок и выполнить с ним необходимые операции.

Функция RasEnumEntries вызывается дважды: при первом вызове она возвращает количество элементов и размер массива, а при втором — непосредственные данные.

Программа вычисляет размер одной структуры RASENTRYNAME и выделяет в неуправляемой памяти блок для ее хранения. Выделение памяти осуществляется методом Marshal.AllocHGlobal.

Sub Main() 

Dim res As Integer 

Dim cb, cbentries As Integer 

Dim idx As Integer 

Dim iptr As IntPtr 

Dim SizePerStruct As Integer

SizePerStruct = Marshal.SizeOf(GetType(RASENTRYNAME))

 ' Получить размер структуры 

iptr = Marshal.AllocHGlobal(SizePerStruct)

Затем мы создаем одну структуру RASENTRYNAME, инициализируем ее и передаем в буфер методом Marshal .StructureToPtr. После вызова метода RasEnumEntries данные возвращаются в структурную переменную методом Marshal. PtrToStructure. Обратите внимание на освобождение буфера в неуправляемой памяти методом Marshal.FreeHGlobal.

Dim rasentries(G) As RASENTRYNAME

rasentries(0).Init()

cb = rasentries(0).dwSize

cbentries = 1

Marshal.StructureToPtr(rasentries(0), iptr, False)

' При первом вызове возвращается количество записей, res = RasEnumEntries(0, Nothing, iptr, cb, cbentries)

rasentries(0) = CType(Marshal.PtrToStructure(iptr, _

GetType(RASENTRYNAME)), RASENTRYNAME) Marshal.FreeHGlobal (iptr)

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

If res = 603 Then 

ReDim rasentries(cbentries - 1)

 cb = 0 iptr = Marshal.AllocHGlobal(cbentries * SizePerStruct)

For idx = 0 To cbentries - 1 

rasentries(idx).Init() 

Marshal.StructureToPtr(rasentries(idx),

 New IntPtr(iptr.Tolnt32 + cb), False)

 cb = cb + rasentries(idx).dwSize

 Next

res = RasEnumEntries(0, Nothing, iptr, cb, cbentries) 

End If

If res = 0 Then cb = 0 For idx = 0 To cbentries - 1

rasentries(idx) = CType(Marshal.PtrToStructure

(New _ IntPtr(iptr.ToInt32 + cb), GetType(RASENTRYNAME)), RASENTRYNAME)

cb = cb + rasentries(idx).dwSize console.WriteLine (rasentries(idx).szEntryName) Next End If Marshal.FreeHGlobal (iptr)

console.ReadLine()

 End Sub

End Module

Итак, средства Visual Basic .NET позволяют выделять блоки в неуправляемой памяти и копировать данные в неуправляемую память и обратно. Более того, VB .NET значительно мощнее VB6, поскольку ваши возможности не ограничиваются простым копированием данных функцией API RtlMoveMemory, часто использовавшейся в подобных ситуациях в VB. Методы Marshal. StructureToPtr HMarshal.PtrToStructure копируют данные с учетом выравнивания и позволяют управлять передачей каждого поля структуры¹.

¹Вероятно, вас интересует, почему я не передаю сразу весь массив структур RASENTRYNAME? Просто мне не удалось заставить работать это решение.^Передача данных массива функции API проходила нормально, но с передачей в обратном направлении возникли проблемы. Система P-Invoke умеет передавать массивы простых типов, но на момент написания книги в документации ничего не говорилось о передаче массивов структур, Пока трудно сказать, что это такое — норма или ошибка в бета-версии.

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

Получение информации об одном соединении функцией API RasGetEntryProperties

Описание конкретной записи телефонной книги хранится в структуре RASENTRY (листинг 15.14), содержащей большое количество полей².

²Как и прежде, мы не используем расширенную версию этой структуры с новыми полями, появившимися в Windows 2000.

Листинг 15.14. Структура RASENTRY (C++)

typedef struct tagRASENTRY {

DWORD dwSize;

DWORD dwfOptions;

//

// Местонахождение/телефон

//

DWORD dwCountrylD;

DWORD dwCountryCode;

TCHAR szAreaCode[ RAS_MaxAreaCode + 1 ];

TCHAR szLocalPhoneNumber[ RAS_MaxPhoneNumber + 1 ];

DWORD dwAlternateOffset;

// PPP/IP //

RASIPADOR ipaddr; RASIPADDR ipaddrDns;

 RASIPADDR ipaddrDnsAlt; 

RASIPADDR ipaddrWins;

 RASIPADDR ipaddrWinsAlt; //

// Сетевой протокол //

DWORD dwFrameSize; 

DWORD dwfNetProtocols; 

DWORD dwFramingProtocol; //

// Сценарии //

TCHAR szScript[ MAX_PATH ]; //

// Автодозвон //

TCHAR szAutodialDllt MAX_PATH ];

 TCHAR szAutodialFunc[ MAX_PATH ]; //

// Устройство //

TCHAR szDeviceType[ RAS_MaxDeviceType + 1 ];

 TCHAR szDeviceName[ RAS_MaxDeviceName + 1 ]; //

// X.25 //

TCHAR szX25PadType[ RAS_MaxPadType + 1 ];

 TCHAR szX25Address[ RAS_MaxX25Address + 1 ];

 TCHAR szX25Facilities[ RAS_MaxFacilities + 1 ] ;

 TCHAR szX25UserData[ RAS_MaxUserData + 1 ]; 

DWORD dwChannels; //

// Зарезервированные поля //

DWORD dwReservedl; DWORD dwReserved2;

 }

 RASENTRY;

Основные трудности преобразования этой структуры в VB .NET связаны с правильным указанием длин всех строк. Объявление, приведенное в листинге 15.15, имеет много общего с предыдущим примером (см. листинг 15.13).

Листинг 15.15. Структура RASENTRY (VB .NET) 

' Приложение RasGetEntry

' Copyright ©2001 by Desaware Inc.

 AU Rights Reserved Imports System.Runtime.InteropServices

Module Modulel

<StructLayout(LayoutKind.Sequential, Pack:=4, CharSet:=charset.Auto)> Structure RASENTRY

Public dwSize As Integer

Public dwfOptions As Integer

Public dwCountrylD As Integer Public dwCountryCode As Integer <MarshalAs(UnmanagedType.ByValTStr, SizeConst:=!!)>

 Public

szAreayCode As String '11 символов 

<MarshalAs(UnmanagedType.ByValTStr, SizeConst:=129)> Public _

szLocalPhoneNumber As String Public dwAlternateOffset As Integer 

Public ipaddr As Integer Public ipaddrDns As Integer 

Public ipaddrDnsAlt As Integer Public ipaddrWins As Integer

 Public ipaddrWinsAlt As Integer

Public dwFrameSize As Integer Public dwfNetProtocols As Integer 

Public dwFramingProtocol As Integer

<MarshalAs(UnmanagedType.ByValTStr, SizeConst:=260)>

 Public szScript As String

<MarshalAs(UnmanagedType.ByValTStr, SizeConst:=260)>

 Public

szAutodialDll As String

 <MarshalAs(UnmanagedType.ByValTStr, SizeConst:=260)> 

Public _

szAutodialFunc As String

<MarshalAs(UnmanagedType.ByValTStr, SizeConst:=17)>

 Public

szDeviceType As String <MarshalAs(UnmanagedType.ByValTStr, SizeConst:=129)> 

Public

szDeviceName As String

<MarshalAs(UnmanagedType.ByValTStr, SizeConst:=33)> 

Public

szX25PadType As String <MarshalAs(UnmanagedType.ByValTStr, SizeConst:=201)> Public

szX25Address As String <MarshalAs(UnmanagedType.ByValTStr, SizeConst:=201)> Public

szFacilities As String <MarshalAs(UnmanagedType.ByValTStr, SizeConst:=201)> Public _

szllserData As String Public dwChannels As Integer

Public dwReservedl As Integer Public dwReserved2 As Integer

 End Structure

Функция RasGetEntryPropertieS определяется в документации MSDN следующим образом:

DWORD RasGetEntryProperties(

 LPCTSTR IpszPhonebook, // Указатель на полное имя файла

// телефонной книги

LPCTSTR IpszEntry, 

// Указатель на имя записи LPRASENTRY IpRasEntry, 

// Буфер, заполняемый данными записи LPDWORD IpdwEntrylnfoSize,

 // Размер буфера IpRasEntry

// в байтах LPBYTE IpbDevicelnfo, 

// Буфер, заполняемый параметрами

// конфигурации для конкретного устройства LPDWORD IpdwpevicelnfoSize 

// Размер буфера IpbDevicelnfo

// в байтах );

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

Public Denction RasGetEntryProperties Lib _ "rasapi32.dU" (ByVal IpszPhoneBook As String, ByVal IpszEntry As String, ByRef IpRasEntry As RASENTRY, ByRef IpdwEntryInfoSize '_ As Integer, ByVal devinfo As Integer, ByVal devinfosize _

As Integer) As Integer

Public Deunction RasGetEntryProperties2 Lib _ "rasapi32.dll" Alias "RasGetEntryProperties" (ByVal _ IpszPhoneBook As String, ByVal IpszEntry As String, ByVal _ IpRasEntry As IntPtr, ByRef IpdwEntrylnfoSize As Integer, _ ByVal devinfo As Integer, ByVal devinfosize As Integer) As Integer

В документации Win32 сказано, что вместо неиспользуемых параметров devinfо можно передать Null. В нашем примере оба параметра объявлены с типом ByVal As Integer, и при вызове функции им присваиваются пули.

Присвойте константе PhoneBookEntryToGet имя записи своей телефонной книги по умолчанию (вряд ли в ней найдется запись с именем DesawareModem). Программа инициализирует поле dwSize правильной длиной, присваивает то же значение переменной bufsize и вызывает функцию RasGetEntryProperties. Const PhoneBookEntryToGet As String = "DesawareModem"

Sub Main()

Dim res As Integer

Dim re As RASENTRY

Dim bufsize As Integer

re.dwSize = Marshal.SizeOf(re)

bufsize = re.dwSize

res = RasGetEntryProperties(Nothing, PhoneBookEntryToGet, re, bufsize. 0, 0)

If res = 623 Then

Console.WriteLine ("Can't find specified dial-up entry")

 End If

Почему вызов может завершиться неудачей? Прежде всего — если в телефонной книге отсутствует запись с указанным именем. Столкнувшись с ошибкой 623, проверьте, не забыли ли вы присвоить константе PhoneBookeEntryToGet имя соединения удаленного доступа в вашей системе.

Но даже если имя соединения задано верно, ошибки все равно возможны, поскольку функция RasGetEntryProperties может возвращать дополнительную информацию об устройстве, выходящую за границы структуры. Подобные ситуации очень часто встречаются при вызове нетривиальных функций API. Иногда в этом дополнительном пространстве хранятся строковые данные, на которые ссылаются указатели в структуре (эти данные также легко извлекаются средствами P-Invoke). Универсальное решение — выделить блок памяти длины, ожидаемой функцией, скопировать структуру в блок, вызвать функцию API и затем скопировать данные обратно, как показано ниже:

If res = 603 Then

Dim iptr As IntPtr 

iptr = Marshal.AllocHGlobal(bufsize)

Marshal.StructureToPtr(re, iptr, False)

res = RasGetEntryProperties2(Nothing, PhoneBookEntryToGet, _

iptr, bufsize, 0, 0) 

re = CType(Marshal.PtrToStructure(iptr, GetType(RASENTRY)),

RASENTRY)

Marshal.FreeHGlobal (iptr)

 End If

Console.WriteLine (re.szLocalPhoneNumber) Console.ReadLine()

 End Sub

End Module

Итоги

Платформа .NET упрощает программирование, но переход на эту платформу может оказаться долгим — очень долгим. Готовые компоненты не переключатся на нее сами по себе. То же самое можно сказать и о других технологиях Microsoft — таких, как Transaction Server и Microsoft Message Queue (как бы они не назывались после очередного переименования). Следовательно, взаимодействие с СОМ и базовыми средствами операционной системы является важнейшей частью .NET Framework.

В этой главе было показано, как просто использовать компоненты СОМ в сборках .NET. Visual Studio выполняет за вас большую часть работы. С использованием компонентов .NET в программах СОМ дело обстоит чуть сложнее, но если ограничиться Automation-совместимыми интерфейсами (такими, как используются в VB6), вам удастся избежать практически всех затруднений, возникающих при работе с другими типами данных. Предоставляя доступ к сборкам .NET из СОМ, необходимо в первую очередь позаботиться о контроле версии, в противном случае может возникнуть знакомая ситуация «кошмара DLL».

Мы подошли к концу одной из моих любимых тем — использования функций API в Visual Basic .NET. В этой области VB .NET превосходит VB6 по гибкости и разнообразию возможностей. Многие функции API в VB .NET вызываются так же просто, как в VB6, однако при вызове сложных функций приходится использовать нетривиальные приемы (кстати говоря, в С# это делается ничуть не проще). Главное, о чем должен помнить программист VB6 при переходе на VB .NET, — что все параметры типа Long заменяются на Integer, а парал; фы типа Integer заменяются на Short.

Назад   Вперёд

 

Инфо Сайт создан: 20 июня 2015 г.

Главная страница

---