Skip to content

Commit 27f3b2f

Browse files
ShrBoxShrBox
committed
docs: add English translation for NativeAPI
docs: remove NativePathch
1 parent e851bfa commit 27f3b2f

File tree

6 files changed

+260
-72
lines changed

6 files changed

+260
-72
lines changed

‎docs/apis/NativeAPI/NativeFunction.md

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
# NativeFunction
2+
3+
This API set contains two types: `NativeFunction` and `NativeHook`, where `NativeHook` is a specialized implementation that only contains `call` and `address` properties.
4+
5+
### Symbol get function
6+
7+
Automatically parse the symbol and get a callable function. If the parsing fails, an exception is thrown.
8+
9+
`static NativeFunction.fromSymbol(symbol)`
10+
11+
- Parameters:
12+
- String: `symbol`
13+
The function to be parsed
14+
- Return value: native function instance
15+
- Return type: `NativeFunction`
16+
17+
18+
19+
### Describe get function
20+
21+
Describe the function type and get an uncallable function. If you need to call it, you also need to manually set the address property.
22+
23+
`static NativeFunction.fromDescription(ReturnValue: NativeTypes.Void, Params: [NativeType.Int......])`
24+
25+
- Parameters:
26+
- Enum-NativeTypes: `ReturnValue`
27+
Return type
28+
- Enum-NativeTypes...: `Params`
29+
Parameter types, passed directly from left to right
30+
- Return value: native function instance
31+
- Return type: `NativeFunction`
32+
33+
34+
35+
### Script get function
36+
37+
Describe the function type and get a function from the script, which is wrapped as a function that can be directly called in native code.
38+
39+
`static NativeFunction.fromScript(ReturnValue: NativeTypes.Void, Params: [NativeType.Int......], Callback: func(Params...){})`
40+
41+
- Parameters:
42+
- Enum-NativeTypes: `ReturnValue`
43+
Return type
44+
- Enum-NativeTypes...: `Params`
45+
Parameter types, passed directly from left to right
46+
- Function: `Callback`
47+
Callback function, which will be called after the native wrapper function is called
48+
- Return value: native function instance
49+
- Return type: `NativeFunction`
50+
51+
52+
53+
### Hook function hook
54+
55+
Rewrite the header of the specified address function, set the callback function, and call the callback function when the original function is called.
56+
If you need to keep the original function, please remember to call the original function in the callback function.
57+
58+
`NativeFunction.hook(function)`
59+
60+
- Parameters:
61+
- Function: `function`
62+
Callback function, please note that the parameter type is consistent with the description of NativeFunction
63+
- Return value: original function
64+
- Return type: `NativeHook`
65+
66+
67+
68+
### call function
69+
70+
Call the corresponding function through the virtual object call.
71+
72+
`NativeFunction.call(params...)`
73+
74+
- Parameters:
75+
- Parameters: `params`
76+
The function parameters described by NativeFunction
77+
- Return value: the return type described by NativeFunction
78+
- Return type: `Value`
79+
80+
81+
82+
### address property
83+
84+
The pointer value of the function pointer
85+
86+
`NativeFunction.address`
87+
88+
- Setter:
89+
- NativePointer
90+
- int64
91+
- Getter
92+
- int64
93+
94+
95+
96+
## NativeType parameter type
97+
98+
This Enum shows all the types that can be used for function parameters and returns
99+
100+
- Void
101+
- Bool
102+
- Char
103+
- UnsignedChar
104+
- Short
105+
- UnsignedShort
106+
- Int
107+
- UnsignedInt
108+
- Long
109+
- UnsignedLong
110+
- LongLong
111+
- UnsignedLongLong
112+
- Float
113+
- Double
114+
- Pointer

‎docs/apis/NativeAPI/NativeFunction.zh.md

Lines changed: 15 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -97,20 +97,19 @@
9797

9898
此Enum展示了所有可用于函数参数以及返回的类型
9999

100-
|Void|
101-
|Bool|
102-
|Char|
103-
|UnsignedChar|
104-
|Short|
105-
|UnsignedShort|
106-
|Int|
107-
|UnsignedInt|
108-
|Long|
109-
|UnsignedLong|
110-
|LongLong|
111-
|UnsignedLongLong|
112-
|Float|
113-
|Double|
114-
|Pointer|
115-
100+
- Void
101+
- Bool
102+
- Char
103+
- UnsignedChar
104+
- Short
105+
- UnsignedShort
106+
- Int
107+
- UnsignedInt
108+
- Long
109+
- UnsignedLong
110+
- LongLong
111+
- UnsignedLongLong
112+
- Float
113+
- Double
114+
- Pointer
116115

‎docs/apis/NativeAPI/NativePatch.zh.md

Lines changed: 0 additions & 51 deletions
This file was deleted.

‎docs/apis/NativeAPI/NativePointer.md

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# NativePointer
2+
3+
This API is designed to help developers manipulate native pointers
4+
5+
> Due to the x64 calling convention, any object (size>8) is passed by reference. To learn more details, please refer to [msdoc: x64 calling convention](https://docs.microsoft.com/cpp/build/x64-calling-convention)
6+
7+
### Memory allocation
8+
9+
This function helps to allocate a block of memory of a specified size
10+
11+
`static NativePointer.malloc(size)`
12+
13+
- Parameters:
14+
- int64: `size`
15+
The size of the memory to be allocated
16+
- Return value: a pointer to the new memory
17+
- Return type: `NativePointer`
18+
19+
20+
21+
### Memory destruction
22+
23+
Destroy a specified block of memory
24+
25+
`static NativePointer.free(block)`
26+
27+
- Parameters:
28+
- NativePointer: `block`
29+
The block of memory to be destroyed
30+
31+
32+
33+
### Pointer offset
34+
35+
Get the address after offsetting relative to a pointer
36+
37+
`NativePointer.offset(offset)`
38+
39+
- Parameters:
40+
- int32: `offset`
41+
42+
- Return value: the pointer after offsetting
43+
- Return type: `NativePointer`
44+
45+
46+
47+
### Get symbol address
48+
49+
Get an MCAPI symbol address, equivalent to `dlsym` in CPP
50+
51+
`NativePointer.fromSymbol(symbol)`
52+
53+
- Parameters:
54+
- String: `symbol`
55+
The symbol to be queried
56+
- Return value: the query result, or a null pointer if the query fails
57+
- Return type: `NativePointer`
58+
59+
60+
61+
### Get address instance
62+
63+
Get a pointer instance of a specified address
64+
65+
`NativePointer.fromAddress(address)`
66+
67+
- Parameters:
68+
- String/int64: `address`
69+
The address, expressed as a hexadecimal string or a number
70+
- Return value: the pointer instance of the corresponding address
71+
- Return type: `NativePointer`
72+
73+
74+
75+
### Get pointer address
76+
77+
Get the raw pointer address
78+
79+
`NativePointer.asRawAddress`
80+
81+
- Return value: the pointer address expressed as a number
82+
- Return type: `int64`
83+
84+
85+
86+
### Get pointer address description
87+
88+
Get the raw pointer address (hexadecimal string)
89+
90+
`NativePointer.asHexAddress`
91+
92+
- Return value: the pointer address expressed as a hexadecimal string
93+
- Return type: `String`
94+
95+
96+
97+
### Read and write pointer memory
98+
99+
The following virtual properties are set up to help access the pointer content. The available types are shown in the table below.
100+
101+
`NativePointer.type`
102+
103+
| Access name | Size | Special notes |
104+
| :---------- | :---: | :------------------------------------------------------------ |
105+
| byte | 1 | This property is read and written through hexadecimal strings |
106+
| int8 | 1 | |
107+
| uint8 | 1 | |
108+
| int16 | 2 | |
109+
| uint16 | 2 | |
110+
| int32 | 3 | |
111+
| uint32 | 4 | |
112+
| long | 4 | |
113+
| ulong | 4 | |
114+
| int64 | 8 | |
115+
| uint64 | 8 | |
116+
| float | 4 | |
117+
| double | 8 | |
118+
| string | 32 | This property represents std::string* |
119+
| bool | 1 | |

‎docs/apis/NativeAPI/Summary.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# 脚本层原生接口（FFI）
2+
3+
通过在脚本层提供FFI（Foreign Function Interface）相关接口，有助于简化小型修复插件的开发过程，并通过脚本引擎获得较为稳定的ABI，便于在多个版本之间共享插件
4+
5+
> 此类API只适用于对非性能敏感的工作流程，对调用者拥有对原生语言较为透彻及准确的理解，否则极容易带来意外的情况。
6+
> 若需要高性能底层接口，请使用原生语言。
7+
> 由于FFI接口规范仍然在设计当中，接口等相关信息可能在没有通知的情况下随时改变。

‎docs/apis/NativeAPI/Summary.zh.md

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
1-
# 脚本层原生接口（FFI）
1+
# Script layer native interface (FFI)
22

3-
通过在脚本层提供FFI（Foreign Function Interface）相关接口，有助于简化小型修复插件的开发过程，并通过脚本引擎获得较为稳定的ABI，便于在多个版本之间共享插件
3+
By providing FFI (Foreign Function Interface) related interfaces in the script layer, it helps to simplify the development process of small repair plugins, and obtain a more stable ABI through the script engine, which is convenient for sharing plugins across multiple versions
44

5-
> 此类API只适用于对非性能敏感的工作流程，对调用者拥有对原生语言较为透彻及准确的理解，否则极容易带来意外的情况。
6-
> 若需要高性能底层接口，请使用原生语言。
7-
> 由于FFI接口规范仍然在设计当中，接口等相关信息可能在没有通知的情况下随时改变。
5+
> This kind of API is only suitable for workflows that are not performance sensitive, and the caller has a thorough and accurate understanding of the native language, otherwise it is very easy to cause unexpected situations.
6+
> If you need high-performance low-level interfaces, please use native languages.
7+
> Since the FFI interface specification is still under design, the interface and related information may change at any time without notice.

0 commit comments

Comments
 (0)