Skip to content

Commit 8d7b011

Browse files
neon-nyanneon-nyan
committed
Adds more docs on SharedStatic
1 parent 2559698 commit 8d7b011

File tree

1 file changed

+76
-19
lines changed

1 file changed

+76
-19
lines changed

‎SharedStatic.cs‎

Lines changed: 76 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ namespace Hi3Helper.Plugin.Core;
3333
/// <param name="hostname">[In] A hostname to resolve to.</param>
3434
/// <param name="ipResolvedWriteBuffer">[Ref] A pointer to the buffer in which the main application will write the UTF-16 unsigned string (with null terminator) to.</param>
3535
/// <param name="ipResolvedWriteBufferLength">[In] The length of the buffer that the main application able to write.</param>
36-
/// <param name="ipResolvedWriteCount">[Out] How many IP address strings (with null terminator) are written into the buffer.</param>
36+
/// <param name="ipResolvedWriteCount">[Out] How many IP address strings (with null terminator) are written into the buffer (<paramref name="ipResolvedWriteBuffer"/>).</param>
3737
public unsafe delegate void SharedDnsResolverCallback(char* hostname, char* ipResolvedWriteBuffer, int ipResolvedWriteBufferLength, int* ipResolvedWriteCount);
3838

3939
/// <summary>
@@ -53,14 +53,35 @@ public class SharedStatic
5353
{
5454
static unsafe SharedStatic()
5555
{
56-
TryRegisterApiExport<GetUnknownPointerDelegate> ("GetPluginStandardVersion", GetPluginStandardVersion);
57-
TryRegisterApiExport<GetUnknownPointerDelegate> ("GetPluginVersion", GetPluginVersion);
58-
TryRegisterApiExport<GetUnknownPointerDelegate> ("GetPlugin", GetPlugin);
59-
TryRegisterApiExport<GetPluginUpdateCdnListDelegate>("GetPluginUpdateCdnList", GetPluginUpdateCdnList);
60-
TryRegisterApiExport<SetCallbackPointerDelegate> ("SetLoggerCallback", SetLoggerCallback);
61-
TryRegisterApiExport<SetCallbackPointerDelegate> ("SetDnsResolverCallback", SetDnsResolverCallback);
62-
TryRegisterApiExport<SetCallbackPointerDelegate> ("SetDnsResolverCallbackAsync", SetDnsResolverCallbackAsync);
63-
TryRegisterApiExport<VoidCallback> ("FreePlugin", DisposePlugin);
56+
// Plugin essential exports (based on v0.1 API Standard)
57+
// ---------------------------------------------------------------
58+
// These exports are required for the minimal plugin
59+
// functionalities in order run. Every plugin must have these
60+
// exports registered to comply the v0.1 API standard.
61+
62+
// -> Plugin Versioning export
63+
TryRegisterApiExport<GetUnknownPointerDelegate>("GetPluginStandardVersion", GetPluginStandardVersion);
64+
TryRegisterApiExport<GetUnknownPointerDelegate>("GetPluginVersion", GetPluginVersion);
65+
// -> Plugin IPlugin Instance Getter export
66+
TryRegisterApiExport<GetUnknownPointerDelegate>("GetPlugin", GetPlugin);
67+
// -> Current's IPlugin Free export
68+
TryRegisterApiExport<VoidCallback>("FreePlugin", FreePlugin);
69+
// -> Plugin Debug Log Callback Setter export
70+
TryRegisterApiExport<SetCallbackPointerDelegate>("SetLoggerCallback", SetLoggerCallback);
71+
// -> Plugin DNS Resolver Callback Setter export
72+
TryRegisterApiExport<SetCallbackPointerDelegate>("SetDnsResolverCallback", SetDnsResolverCallback);
73+
74+
// Plugin optional exports (based on v0.1-update1 API Standard)
75+
// ---------------------------------------------------------------
76+
// These exports are optional and can be removed if it's not
77+
// necesarilly used. These optional exports are included under
78+
// additional functionalities used as a subset of v0.1, which is
79+
// called "update1" feature sets.
80+
81+
// -> Plugin Update CDN List Getter export
82+
TryRegisterApiExport<GetPluginUpdateCdnListDelegate>("GetPluginUpdateCdnList", GetPluginUpdateCdnList);
83+
// -> Plugin Async DNS Resolver Callback Setter export
84+
TryRegisterApiExport<SetCallbackPointerDelegate>("SetDnsResolverCallbackAsync", SetDnsResolverCallbackAsync);
6485
}
6586

6687
#region Private Static Fields
@@ -94,8 +115,13 @@ static unsafe SharedStatic()
94115

95116
protected unsafe delegate void* GetUnknownPointerDelegate();
96117
protected unsafe delegate void GetPluginUpdateCdnListDelegate(int* count, ushort*** ptr);
97-
protected delegate void SetCallbackPointerDelegate(nint callbackP);
118+
protected delegate void SetCallbackPointerDelegate(nint callbackP);
98119

120+
/// <summary>
121+
/// Gets the array of CDN URLs used by the launcher to perform an update.
122+
/// </summary>
123+
/// <param name="count">[Out] The pointer to the count of the array.</param>
124+
/// <param name="ptr">[Out] The pointer to the array of the CDN URL strings.</param>
99125
private static unsafe void GetPluginUpdateCdnList(int* count, ushort*** ptr)
100126
{
101127
try
@@ -137,6 +163,9 @@ private static unsafe void GetPluginUpdateCdnList(int* count, ushort*** ptr)
137163
}
138164
}
139165

166+
/// <summary>
167+
/// Gets the pointer of the current API Standard version in which the plugin use.
168+
/// </summary>
140169
private static unsafe void* GetPluginStandardVersion()
141170
{
142171
fixed (void* ptr = &LibraryStandardVersion)
@@ -145,19 +174,19 @@ private static unsafe void GetPluginUpdateCdnList(int* count, ushort*** ptr)
145174
}
146175
}
147176

177+
/// <summary>
178+
/// Gets the pointer of the current plugin's version.<br/>
179+
/// If DebugNoReflection or ReleaseNoReflection build configuration is used, the pointer of <see cref="_currentDllVersion"/> will be returned.
180+
/// Otherwise, the plugin will auto-detect the version defined by the .csproj file (via <see cref="System.Reflection.Assembly"/>).
181+
/// </summary>
148182
private static unsafe void* GetPluginVersion()
149183
{
150-
if (_currentDllVersion != GameVersion.Empty)
151-
{
152-
return _currentDllVersion.AsPointer();
153-
}
154-
155184
try
156185
{
157186
Version? versionAssembly = _thisPluginInstance?.GetType().Assembly.GetName().Version;
158187
if (versionAssembly == null)
159188
{
160-
InstanceLogger.LogTrace("versionFromIPluginAssembly is null");
189+
InstanceLogger.LogTrace("versionAssembly is null");
161190
return _currentDllVersion.AsPointer();
162191
}
163192

@@ -170,13 +199,20 @@ private static unsafe void GetPluginUpdateCdnList(int* count, ushort*** ptr)
170199
}
171200
}
172201

202+
/// <summary>
203+
/// Gets the COM interface pointer of the <see cref="IPlugin"/> instance.
204+
/// </summary>
173205
private static unsafe void* GetPlugin()
174206
#if !MANUALCOM
175207
=> ComInterfaceMarshaller<IPlugin>.ConvertToUnmanaged(_thisPluginInstance);
176208
#else
177209
=> ComWrappersExtension<PluginWrappers>.GetComInterfacePtrFromWrappers(_thisPluginInstance);
178210
#endif
179211

212+
/// <summary>
213+
/// Sets the pointer of the Debug Log callback/<see cref="SharedLoggerCallback"/> from the main application.
214+
/// </summary>
215+
/// <param name="loggerCallback">[In] A pointer to the Debug Log callback/<see cref="SharedLoggerCallback"/>.</param>
180216
private static void SetLoggerCallback(nint loggerCallback)
181217
{
182218
if (loggerCallback == nint.Zero)
@@ -190,6 +226,10 @@ private static void SetLoggerCallback(nint loggerCallback)
190226
InstanceLoggerCallback = Marshal.GetDelegateForFunctionPointer<SharedLoggerCallback>(loggerCallback);
191227
}
192228

229+
/// <summary>
230+
/// Sets the pointer of the Asynchronous DNS Resolver callback/<see cref="SharedDnsResolverCallbackAsync"/>
231+
/// </summary>
232+
/// <param name="dnsResolverCallback">[In] A pointer to the Asynchronous DNS Resolver callback/<see cref="SharedDnsResolverCallbackAsync"/>.</param>
193233
private static void SetDnsResolverCallbackAsync(nint dnsResolverCallback)
194234
{
195235
if (dnsResolverCallback == nint.Zero)
@@ -208,6 +248,10 @@ private static void SetDnsResolverCallbackAsync(nint dnsResolverCallback)
208248
InstanceDnsResolverCallbackAsync = Marshal.GetDelegateForFunctionPointer<SharedDnsResolverCallbackAsync>(dnsResolverCallback);
209249
}
210250

251+
/// <summary>
252+
/// Sets the pointer of the DNS Resolver callback/<see cref="SharedDnsResolverCallback"/>
253+
/// </summary>
254+
/// <param name="dnsResolverCallback">[In] A pointer to the DNS Resolver callback/<see cref="SharedDnsResolverCallback"/>.</param>
211255
private static void SetDnsResolverCallback(nint dnsResolverCallback)
212256
{
213257
if (dnsResolverCallback == nint.Zero)
@@ -221,8 +265,21 @@ private static void SetDnsResolverCallback(nint dnsResolverCallback)
221265
InstanceDnsResolverCallback = Marshal.GetDelegateForFunctionPointer<SharedDnsResolverCallback>(dnsResolverCallback);
222266
}
223267

224-
private static void DisposePlugin() => _thisPluginInstance?.Free();
268+
/// <summary>
269+
/// Free the current instance of this plugin's <see cref="IPlugin"/>.
270+
/// </summary>
271+
private static void FreePlugin() => _thisPluginInstance?.Free();
225272

273+
/// <summary>
274+
/// Sets the locale ID to use by the launcher. The format must be in IETF BCP-47 format with no region subtag.<br/>
275+
/// A valid format example as follows:<br/>
276+
/// br-BR, id-ID, es-419, en-US
277+
/// </summary>
278+
/// <remarks>
279+
/// This method is used to set what language/locale ID is used to perform API request by the <see cref="Hi3Helper.Plugin.Core.Management.Api.ILauncherApi"/> members.<br/>
280+
/// The locale ID might be used to grab the data of the game news/launcher content based on user's current language.
281+
/// </remarks>
282+
/// <param name="currentLocale">The string represents the IETF BCP-47 non-region subtag locale ID.</param>
226283
internal static void SetPluginCurrentLocale(ReadOnlySpan<char> currentLocale)
227284
{
228285
if (currentLocale.IsEmpty)
@@ -279,8 +336,8 @@ public static bool TryRegisterApiExport<T>(string apiExportName, T callback)
279336
/// <summary>
280337
/// Retrieve the pointer of the API exports from the lookup table.
281338
/// </summary>
282-
/// <param name="apiExportName">The name of the key for the delegate pointer.</param>
283-
/// <param name="delegateP">The pointer to the delegated function.</param>
339+
/// <param name="apiExportName">[In] The name of the key for the delegate pointer.</param>
340+
/// <param name="delegateP">[Out] The pointer to the delegated function.</param>
284341
/// <returns><c>0</c> if it's been registered. Otherwise, <see cref="int.MinValue"/> if not registered or if <paramref name="apiExportName"/> is undefined/null.</returns>
285342
public static unsafe int TryGetApiExportPointer(char* apiExportName, void** delegateP)
286343
{

0 commit comments

Comments
 (0)