Lib.RegisterFunction - Revision history

Admin: 1 revision imported

2025-01-22T06:54:17Z

1 revision imported

1>Admin at 06:31, 2 November 2024

2024-11-02T06:31:57Z

Admin: 1 revision imported

2023-06-08T10:11:40Z

1 revision imported

1>Admin at 18:09, 15 May 2023

2023-05-15T18:09:29Z

Admin: 1 revision imported

2021-06-28T07:02:26Z

1 revision imported

1>Admin at 09:02, 21 June 2021

2021-06-21T09:02:35Z

Admin: 1 revision imported

2021-02-07T06:51:38Z

1 revision imported

Admin at 18:52, 24 June 2020

2020-06-24T18:52:44Z

New page

{{infobox function
|name=RegisterFunction
|object=[[Объект загружаемой системной библиотеки|Библиотека]]
|caption=Импорт функции
|type=1
|status=2
|db=0
|exception=Невозможно превратить в строку, функция не найдена
|visual=0}}
{{HeadLinks|
* [[Main_Page|Начальная страница]]
* [[Общее_описание_языка|Общее описание]]
* [[Объекты]]
* [[Объект загружаемой системной библиотеки|Библиотека]]}}
Функция производит попытку импорта функции по ее имени из библиотеки, если функция найдена, она будет добавлена к функциям, которые возможно вызвать из данного объекта. Для функции задается, если необходимо, список и типы данных аргументов, а также тип данных возвращаемого значения, если оно присутствует.

== Синтаксис ==
<code>
{{Grey|Lib.}}'''RegisterFunction'''(''<Имя функции (STRING)>''{{Optional|<Способ вызова (STRING)>{{Default|{{Eq}}"Stdcall"}},<Аргументы функции (STRING)>,<Возвращаемое значение (STRING)>}})
</code>
==== Аргументы ====
* <code>''<Имя функции (STRING)>''</code> - Аргумент задает точное имя импортируемой функции и, если необходимо, локальное имя функции, с помощью которого она может быть вызвана из программы. Формат аргумента следующий: <code><Имя функции для импорта>[:<Локальное имя для вызова>]</code>. Если часть с локальным именем не используется, функция будет зарегистрирована под своим именем импорта.
* <code>''<Способ вызова (STRING)>''</code> - {{Optional}} Аргумент задает способ вызова функции (см. [[Объект загружаемой системной библиотеки|статью]] для дополнительной информации). Возможны следюущие значения аргумента:
** '''stdcall''' (x86,x64) -- стандартный способ вызова функций Windows, используется по умолчанию. Для x64 является единственным доступным способом вызова.
** '''cdecl''' (x86) -- используется при вызове функций, скомпилированных с помощью C или C++. Система позволяет использование такого способа вызова вместо вызовов stdcall, но не наоборот. Если для библиотек, скомпилированных со способом вызова cdecl указать способ вызова stdcall, можно получить порчу памяти или привести клиент нерабочее состояние.
** '''fastcall''' (x86) -- используется при вызове функций, скомпилированных с помощью C или C++. Несовместим с другими способами вызова.
** '''register''' (x86) -- используется при вызове функций, скомпилированных с помощью Delphi или Free Pascal. Несовместим с другими способами вызова. Важно понимать, что, возможно, придется пометить некоторые параметры при вызове таких функций с помощью префикса "+" (см. ниже).
** '''vectorcall''' (x86,x64) -- способ вызова, оперирующий длинными числами (128 бит), в данный момент не поддерживается.
* <code>''<Аргументы функции (STRING)>''</code> - {{Optional}} Задает список и тип аргументов, передаваемых функции. Строка имеет следующий формат: <code><Аргумент 1>,<Аргумент 2>,...</code>. Где ''аргумент'' имеет следующий формат: <code>[<Префиксы типа данных>]<Тип данных аргумента>[<Размер типа данных>]</code>. Далее даются все возможные префиксы и наименования типов данных:
** '''^''' (префикс) -- определяет то, что аргумент будет являться ссылкой (указателем, ''pointer'') на данные, а не самими данными.
** '''^^''' (префикс) -- определяет то, что аргумент будет являться ссылкой (указатель, ''pointer'') на ссылку на данные, а не самими данными. Префикс можно эмулировать с помощью манипуляции с буфером данных.
** '''@''' (префикс) -- определяет то, что аргумент будет являться ссылкой (указателем, ''pointer'') на данные, а не самими данными. Также помечает аргументы "by ref", т.е., рагументы, значение которых может быть изменено функцией и должно быть передано назад в вызывавшую программу. '''Важно''': без этого префикса, измененные функцией значения будут утеряны. Префикс может дополняться префиксом ''^'', если необходимо.
** '''U''' (префикс) -- используется для типов ''I'' или ''N'', указывает на то, что данные представляют собой беззнаковое число (по умолчанию число со знаком)
** '''#''' (префикс) -- определяет то, что выделение памяти для аргументов (к примеру, для передаваемых строк), будет происходить с помощью системной функции GlobalAlloc. Некоторые типы вызовов могут требовать такой подход.
** '''~''' (префикс) -- определяет то, что выделенная под аргумент память не будет освобождена после выполнения функции. Этой опцией нужно пользоваться с особой осторожностью, так как неверное ее использование может привести к бесконтрольным утечкам памяти.
** '''+''' (префикс) -- определяет то, что данный аргумент всегда будет передаваться в стек, а не с помощью регистра процессора. Флаг имеет значение только для способа вызова функции ''register''. Для его использования необходимо полностью понимать, как работает вызов функции (calling convention) такого типа. Обычно нет необходимости в использовании этого префикса, система сама правильно определит какие аргументы будут передаваться в стек, а какие с помощью регистров.
** '''I<Размер в битах>''' или '''Int<Размер в битах>''' (наименование типа данных) -- задает целый тип аргумента. Размер может принимать следующие значения: '''8''', '''16''', '''32''', '''64'''.
** '''N''' или '''Native''' (наименование типа данных) -- задает целый тип аргумента с размером текущей архитектура исполнения. Для ''x86'' длина поля будет поставлять 32 бита, для ''x64'' -- 64 бита.
** '''R<Размер в битах>''' или '''Real<Размер в битах>''' (наименование типа данных) -- задает вещественный тип аргумента. Размер может принимать следующие значения: '''32''' (одинарная точность), '''64''' (двойная точность), '''80''' (расширенная точность). Расширенная точность не поддерживается при стандартных вызовах "x64" функций, при написании расширения программы, можно пользоваться, к примеру, ссылкой на вещественное число ('''P''') и получение его из буфера.
** '''B<Размер в битах>''' или '''Bool<Размер в битах>''' (наименование типа данных) -- задает булевый тип аргумента. Размер может принимать следующие значения: '''8''', '''16''', '''32''', '''64'''.
** '''P''' или '''Pointer''' (наименование типа данных) -- задает тип данных указателя на данные. Для ''x86'' длина поля будет поставлять 32 бита, для ''x64'' -- 64 бита. При вызове функцией в аргументы такого типа удобно передавать объекты буфера или записи.
** '''SZ<Размер в байтах>''' или '''SZW<Размер в словах>''' (наименование типа данных) -- задает аргумент с типом строка, заканчивающаяся нулевым символом. Строка может иметь формат ANSI (''SZ'') или UTF-16 (''SZW''). Строки всегда должны быть объявлены с префиксом ''^'' (ссылка на данные). Размер может принимать нулевое значение, если заранее неизвестно, строка какого размера будет использоваться. В случае нулевого размера, однако, при подготовке аргумента, размер будет выделен точно под строку. Кроме строковых значений, система принимает также буферы или записи (для которых вызов выполняется несколько быстрее, чем для строк).
** '''S<Размер в байтах>''' или '''SW<Размер в словах>''' (наименование типа данных) -- задает аргумент с типом строка фиксированной длины. Строка может иметь формат ANSI (''S'') или UTF-16 (''SW''). Строки всегда должны быть объявлены с префиксом ''^'' (ссылка на данные). Размер может принимать нулевое значение, если заранее неизвестно, строка какого размера будет использоваться. В случае нулевого размера, однако, при подготовке аргумента, размер будет выделен точно под строку. Кроме строковых значений, система принимает также буферы (для которых вызов выполняется несколько быстрее, чем для строк).
* <code>''<Возвращаемое значение (STRING)>''</code> - {{Optional}} Имеет формат одного аргумента функции (см. выше), если аргумент опущен, возвращаемое функцией значение будет игнорировано (функция не возвращает значения).

== Примеры ==
<pre>
Function ПолучитьИмяПользователя()
aAdvapi32:=Lib.Load("advapi32.dll");
aAdvapi32.RegisterFunction("GetUserNameW:GetUserName","stdcall","@SZW,@UN","B32");
аИмя:=RepeatStr(" ",256);
аДлина:=Length(аИмя);
аДлина0:=аДлина;
While not aAdvapi32.GetUserName(аИмя,аДлина) Do
//Недостаточный размер буфера
аИмя:=RepeatStr(" ",аДлина0*2);
аДлина:=Length(аИмя);
аДлина0:=аДлина;
EndDo;
Exit аИмя;
EndFunction;

Message(ПолучитьИмяПользователя());
</pre>

← Older revision	Revision as of 06:54, 22 January 2025
(No difference)

@@ Line 17: / Line 17: @@
 == Синтаксис ==
 <code>
-{{Grey|Lib.}}'''RegisterFunction'''(''<Имя функции (STRING)>''{{Optional|<Способ вызова (STRING)>{{Default|{{Eq}}"Stdcall"}},<Аргументы функции (STRING)>,<Возвращаемое значение (STRING)>}})
+{{Grey|Lib.}}'''RegisterFunction'''(''<Имя функции (STRING)>''{{Optional|<Способ вызова (STRING)>{{Default|{{Eq}}"Stdcall"}},<Аргументы функции (STRING)>,<Возвращаемое значение (STRING)>,<Системный адрес функции (INT)>}})
 </code>
 ==== Аргументы ====
@@ Line 43: / Line 43: @@
 ** '''S<Размер в байтах>''' или '''SW<Размер в словах>''' (наименование типа данных) -- задает аргумент с типом строка фиксированной длины. Строка может иметь формат ANSI (''S'') или UTF-16 (''SW''). Строки всегда должны быть объявлены с префиксом ''^'' (ссылка на данные). Размер может принимать нулевое значение, если заранее неизвестно, строка какого размера будет использоваться. В случае нулевого размера, однако, при подготовке аргумента, размер будет выделен точно под строку. Кроме строковых значений, система принимает также буферы (для которых вызов выполняется несколько быстрее, чем для строк).
 * <code>''<Возвращаемое значение (STRING)>''</code> - {{Optional}} Имеет формат одного аргумента функции (см. выше), если аргумент опущен, возвращаемое функцией значение будет игнорировано (функция не возвращает значения).
 == Примеры ==

← Older revision	Revision as of 10:11, 8 June 2023
(No difference)

@@ Line 21: / Line 21: @@
 ==== Аргументы ====
 * <code>''<Имя функции (STRING)>''</code> - Аргумент задает точное имя импортируемой функции и, если необходимо, локальное имя функции, с помощью которого она может быть вызвана из программы. Формат аргумента следующий: <code><Имя функции для импорта>[:<Локальное имя для вызова>]</code>. Если часть с локальным именем не используется, функция будет зарегистрирована под своим именем импорта.
-* <code>''<Способ вызова (STRING)>''</code> - {{Optional}} Аргумент задает способ вызова функции (см. [[Объект загружаемой системной библиотеки|статью]] для дополнительной информации). Возможны следюущие значения аргумента:
+* <code>''<Способ вызова (STRING)>''</code> - {{Optional}} Аргумент задает способ вызова функции (см. [[Объект загружаемой системной библиотеки|статью]] для дополнительной информации). Возможны следующие значения аргумента:
 ** '''stdcall''' (x86,x64) -- стандартный способ вызова функций Windows, используется по умолчанию. Для x64 является единственным доступным способом вызова.
 ** '''cdecl''' (x86) -- используется при вызове функций, скомпилированных с помощью C или C++. Система позволяет использование такого способа вызова вместо вызовов stdcall, но не наоборот. Если для библиотек, скомпилированных со способом вызова cdecl указать способ вызова stdcall, можно получить порчу памяти или привести клиент нерабочее состояние.
@@ Line 36: / Line 36: @@
 ** '''+''' (префикс) -- определяет то, что данный аргумент всегда будет передаваться в стек, а не с помощью регистра процессора. Флаг имеет значение только для способа вызова функции ''register''. Для его использования необходимо полностью понимать, как работает вызов функции (calling convention) такого типа. Обычно нет необходимости в использовании этого префикса, система сама правильно определит какие аргументы будут передаваться в стек, а какие с помощью регистров.
 ** '''I<Размер в битах>''' или '''Int<Размер в битах>''' (наименование типа данных) -- задает целый тип аргумента. Размер может принимать следующие значения: '''8''', '''16''', '''32''', '''64'''.
-** '''N''' или '''Native''' (наименование типа данных) -- задает целый тип аргумента с размером текущей архитектура исполнения. Для ''x86'' длина поля будет поставлять 32 бита, для ''x64'' -- 64 бита.
+** '''N''' или '''Native''' (наименование типа данных) -- задает целый тип аргумента с размером, задаваемым текущей архитектурой исполнения приложения. Для ''x86'' длина поля будет представлять 32 бита, для ''x64'' -- 64 бита.
 ** '''R<Размер в битах>''' или '''Real<Размер в битах>''' (наименование типа данных) -- задает вещественный тип аргумента. Размер может принимать следующие значения: '''32''' (одинарная точность), '''64''' (двойная точность), '''80''' (расширенная точность). Расширенная точность не поддерживается при стандартных вызовах "x64" функций, при написании расширения программы, можно пользоваться, к примеру, ссылкой на вещественное число ('''P''') и получение его из буфера.
 ** '''B<Размер в битах>''' или '''Bool<Размер в битах>''' (наименование типа данных) -- задает булевый тип аргумента. Размер может принимать следующие значения: '''8''', '''16''', '''32''', '''64'''.
-** '''P''' или '''Pointer''' (наименование типа данных) -- задает тип данных указателя на данные. Для ''x86'' длина поля будет поставлять 32 бита, для ''x64'' -- 64 бита. При вызове функцией в аргументы такого типа удобно передавать объекты буфера или записи.
+** '''P''' или '''Pointer''' (наименование типа данных) -- задает тип данных указателя на данные. Для ''x86'' длина поля будет поставлять 32 бита, для ''x64'' -- 64 бита. При вызове функцией в аргументы такого типа удобно передавать объекты буфера или записи. Также можно задавать аргументы с типом [[Lib.CreateCallbackFunction|Функция обработного вызова]], что может часто использоваться в процессе выполнения сложных функций.
 ** '''SZ<Размер в байтах>''' или '''SZW<Размер в словах>''' (наименование типа данных) -- задает аргумент с типом строка, заканчивающаяся нулевым символом. Строка может иметь формат ANSI (''SZ'') или UTF-16 (''SZW''). Строки всегда должны быть объявлены с префиксом ''^'' (ссылка на данные). Размер может принимать нулевое значение, если заранее неизвестно, строка какого размера будет использоваться. В случае нулевого размера, однако, при подготовке аргумента, размер будет выделен точно под строку. Кроме строковых значений, система принимает также буферы или записи (для которых вызов выполняется несколько быстрее, чем для строк).
 ** '''S<Размер в байтах>''' или '''SW<Размер в словах>''' (наименование типа данных) -- задает аргумент с типом строка фиксированной длины. Строка может иметь формат ANSI (''S'') или UTF-16 (''SW''). Строки всегда должны быть объявлены с префиксом ''^'' (ссылка на данные). Размер может принимать нулевое значение, если заранее неизвестно, строка какого размера будет использоваться. В случае нулевого размера, однако, при подготовке аргумента, размер будет выделен точно под строку. Кроме строковых значений, система принимает также буферы (для которых вызов выполняется несколько быстрее, чем для строк).

← Older revision	Revision as of 07:02, 28 June 2021
(No difference)

@@ Line 30: / Line 30: @@
 ** '''^''' (префикс) -- определяет то, что аргумент будет являться ссылкой (указателем, ''pointer'') на данные, а не самими данными.
 ** '''^^''' (префикс) -- определяет то, что аргумент будет являться ссылкой (указатель, ''pointer'') на ссылку на данные, а не самими данными. Префикс можно эмулировать с помощью манипуляции с буфером данных.
-** '''@''' (префикс) -- определяет то, что аргумент будет являться ссылкой (указателем, ''pointer'') на данные, а не самими данными. Также помечает аргументы "by ref", т.е., рагументы, значение которых может быть изменено функцией и должно быть передано назад в вызывавшую программу. '''Важно''': без этого префикса, измененные функцией значения будут утеряны. Префикс может дополняться префиксом ''^'', если необходимо.
+** '''@''' (префикс) -- определяет то, что аргумент будет являться ссылкой (указателем, ''pointer'') на данные, а не самими данными. Также помечает аргументы "by ref", т.е., аргументы, значение которых может быть изменено функцией и должно быть передано назад в вызывавшую программу. '''Важно''': без этого префикса, измененные функцией значения будут утеряны. Префикс может дополняться префиксом ''^'', если необходимо.
 ** '''U''' (префикс) -- используется для типов ''I'' или ''N'', указывает на то, что данные представляют собой беззнаковое число (по умолчанию число со знаком)
 ** '''#''' (префикс) -- определяет то, что выделение памяти для аргументов (к примеру, для передаваемых строк), будет происходить с помощью системной функции GlobalAlloc. Некоторые типы вызовов могут требовать такой подход.

← Older revision	Revision as of 06:51, 7 February 2021
(No difference)