Unter Windows-API sollen möglichst alle API-Funktionen gesammelt werden, inklusive der notwendigen Deklarationen Beschreibungen und Datenstrukturen wie Const Enum und Typen. Auch Beispiel können eingefügt werden auf die verwiesen werden kann.
Mit ApiHelper können diese Daten Angezeigt werden, um einfach und schnell Deklarationen für die eigenen Programme zusammenstellen zu können.
Inhalt-Kategorie und Inhalt-Index sind zwei sortierte Inhaltsverzeichnisse. (Sie sind schreibgeschützt da sie automatisch aus den bestehenden Daten erstellt wurden.)
Das Datenpacket ist noch nicht vollständig, die Deklarationen für weitere Bibliotheken ist im Aufbau.
Im Moment werden nur Windows-32 APIs erstellt (die hauptsächlich aus den Dateien "msvb7api.txt" und "win32api.txt" stammen), aber wenn dieses Datenpacket einmal fertig ist werden vielleicht auch noch andere Systemumgebungen hinzugefügt.
Auch über die [Suche] Oben-Links kann verwendet werden um Funktionen zu finden.
Die Texte sind noch im Aufbau. Es fehlen noch die Const/Enum/Type Deklarationen zu den Funktionen (Include).
Die Deklarationen sind etwas anders formatiert als es dem VB Syntax entspringt, um möglichst viele Informationen aufnehmen zu können und auch kompatibel für andere Basic-Sprachen zu sein. ApiHelper wird diese Formate für VB6 kompatibel konvertieren.
Es gibt viele Quellen für Deklarationen die sich in einigen Formaten teilweise widersprüchlich unterscheiden. Es kann also nicht ausgeschlossen werden, das einige Deklarationen Fehler enthalten. (Ein typischer Konflikt besteht zwischen ByRef und ByVal Deklaration, oder auch falsche Variabel-Typen. Auch die Präfixe für die Parameternamen sind manchmal widersprüchlich. Falsche Deklaration kann auch zu einem Absturz des Programms führen.)
Auf folgendes wurde bei der Korrektur der Deklaration geachtet:
Es werden
Unsigned Typen deklariert so wie es dem C basierenden API-Funktionen entspricht.
Einige Parameter können auch manuell noch an spezielle Anforderungen angepaßt werden. zB. lassen sich Typen auch durch Long-Zeiger ersetzen. VB6 wandelt Strings Automatisch vom internen Unicode-Format in Ascii um und übergibt immer den Zeiger des Strings, unabhängig ob der
String ByRef oder ByVal übergeben wird. Bei einer ByVal Übergabe wird kein Resultat zurückkopiert. Deshalb könnten Strings auch als Long-Zeiger übergeben werden.
Zeiger werden nach dem Variabel-Type mit den Schlüsselwort
PTR gekennzeichnet
Zeiger werden nicht als "ByVal As
DWord" sondern als "ByRef As Any" deklariert, da diese eindeutig erkennbare Schreibweise von ApiHelper umgewandelt werden kann. VB6 selbst kennt intern keine Zeiger, sie können aber mit den Funktionen VarPtr StrPtr ObjPtr ermittelt werden.
Falls ein Type übergeben wird, sollte dieser auch mit dem Type-Namen deklariert werden nicht mit Any.
Es werden alle Parameter die keine Rückgaben übernehmen also reine
Eingabe-Parameter als
ByVal deklariert (auch
String und Typen, diese werden Immer als Zeiger übergeben).
Um VB-
String unterscheiden zu können werden die API-Strings
AsciiZ genannt, um zu kennzeichnen das es sich um Text handelt und um ein Null-Terminierten
String.
String gilt anders als in VB6 als ein Binär
String der auch Null enthalten kann und damit die Länge zusätzlich übergeben muß, da kein Null-Terminator ausgewertet werden kann.
Einige wenige Parameter übernehmen kein Ascii sondern Unicode formatierte Strings. Diese werden eindeutig als UnicodeZ deklariert und müssen im Code beachtet werden, da VB die internen Unicode Strings vor der Übergabe zuerst in Ascii umwandelt. Im Code muß dazu StrConv() zur Parameterübergabe verwendet werden. (Intern verwendet VB6 immer Unicode, sobald diese aber nach außen geschrieben werden, werden die Strings zu Ascii konvertiert, und umgekehrt beim Lesen zu Unicode.)
Einige Parameter enthalten
8Byte Integer (
QUAD), die zB. für Datei-Zeiger verwendet werden können um Dateien die größer sind als 2GB zu behandeln. Da VB diese nicht kennt müssen sie aus zwei Long Werten zusammengesetzt werden, die als Type deklariert werden. Solche Funktionen können in VB6 Probleme verursachen da ein solcher Wert nicht korrekt mit zwei Signet Integern abgebildet werden kann. Dazu müßten spezielle Funktionen programmiert werden die Berechnungen mit QUAD unter VB ermöglichen.
Um also mit dem leider in der Beziehung nicht sauber entwickelten VB6 zurecht zu kommen, müssen einige Dinge im Umgang mit API-Funktionen die aus der C-Programmiersprache stammen, berücksichtigt werden. (VB6 kennt keine Unsigned Typen und keine Zeiger.)
Von ApiHelper (optional) durchgeführte Deklarations-Konvertierungen in das VisualBasic-6 Format:
| Declare | Konvertierung zu VB6 | Hinweis |
| Word | Integer | ACHTUNG: VB6 kann unsigned Word nicht exakt abbilden, Werte über 32767 werden Negativ (signed). |
| DWord | Long | ACHTUNG: VB6 kann unsigned DWord nicht exakt abbilden, Werte über 2147483647 werden Negativ (signed). |
| Quad | (QUAD-Type, entspricht LARGE_INTEGER) | ACHTUNG: VB6 kennt kein 8Byte Integer überhaupt nicht. da QUAD aus zwei Long werten gebildet wird muß dabei unbedingt beachtet werden das ein QUAD nicht korrekt mit Signed-Integer verwendet werden kann. Es gibt die Möglichkeit auch Currency dazu zu verwenden, dabei muß aber berücksichtigt werden das VB6 diesen mit einem fixen Fließpunkt interpretiert und mit ebenfalls kein Byte Integer abbildet. |
| AsciiZ | String | String mit Null-Terminator, VB6 benutzt Intern Unicode String, sobald die aber nach außen geschrieben werden, werden diese automatisch zu Ascii umgewandelt, der Null-Terminator wird dabei immer gesetzt und an Api-Deklarationen wird ein Zeiger auf die Konvertierten Daten übergeben.) |
| UnicodeZ | String | ACHTUNG: Intern verwendet VB6 zwar Unicode, diese werden aber Automatisch zu Ascii umgewandelt wenn ein String an eine Declare Funktion übergeben wird. um dies zu verhindern muß der String mit StrConv(String, vbUnicode) übergeben werden. |
| PTR | ByRef as Any, (Zeiger) | ACHTUNG: VB6 kennt ebenfalls keine Zeiger (Pointer). ein Zeiger wird in einer 32Bit Umgebung (Win32) immer als 4Byte integer (DWord) abgebildet. Es muß also berücksichtigt werden das dieser Parameter auch als Zeiger übergeben wird. dazu gibt es die Funktionen StrPtr() ... welche die Speicheradresse/Zeiger/Pointer des Parameters zurückgeben. Deklarationen mit PTR werden zu "ByRef as Any" umgewandelt, und dieser wiederum optional zu "ByVal as Long" (siehe unten.) |
| ByRef as Any | ByVal as Long | (Optional) Mit "ByRef as Any" ist es möglich einen Parameter eines beliebigen Typs zu übergeben. Wobei dieser als Zeiger übergeben wird. Wird dieser (Optional) als "ByVal as Long" konvertiert, muß beachtet werden das die Funktion ein Zeiger und nicht ein Wert erwartet und dieser muß mit VarPtr StrPtr ObjPtr übergeben werden. |
Damit diese Anzeige im ApiHelper funktioniert muß das Daten-Textformat exakt eingehalten werden damit das Programm die Informationen korrekt erkennen kann.
Dazu gibt es Beispiele für:
Format-Funktionen Eine Datei für eine Funktion in einer Bibliothek
Format-Include Eine Datei für Konstanten/Typen/Enum und für Beispiele für eine Bibliothek
Dies ist das Format wenn alle Funktionen in einzelnen Dateien gesammelt werden, da einige Bibliotheken für das Wiki zu groß sind um alle Funktionen in einer Datei unterzubringen.
Dieses Format unterschiedet sich von "Text-Format (Eine Bibliothek)" nur darin, das die Überschriften für "Bibliothek" und "Kategorie" weggelassen werden und die Kategorie bei den Informationen eingetragen wird.
Die Überschriftebenen werden als Gruppierung verwendet.
==== Funktionsname ====
=== @Parameter ===
Dritten Ebene unter dem Funktionsnamen enthält eine Tabelle die Informationen zu dieser Funktion. Um die Informationen erkennen zu können erhalten sie ein Tabellenüberschriftszeichen "^" damit diese Zelle hervorgehoben wird. Alle Texte die nicht diese Schlüsselwörter enthalten, werden vom ApiHelper unter Notizen angezeigt.
| Kategorie | Zuordnung |
| Deklaration | Declare-Deklarationssyntax. |
| Beschreibung | Kürze Beschreibung der Funktion. |
| Systeme | Funktion ist verfügbar in diesen Betriebsystemen, zB. (Win95; Win98; WinME; WinNT31; Win2000; WinXP) |
| Rückgabe | = Wert, wenn die Ausführung erfolgreich war.
= Wert, wenn die Ausführung fehlerhaft war. |
| Include | Zugehörige Deklarationen (Const/Enum/Type) die für diese Funktion notwendig sind. (Entspricht den Einträgen unter @Include.) |
| Beispiele | Verfügbare Beispiele zu dieser Funktion. (Entspricht den Einträgen unter @Beispiele.) |
In der Parameterbeschreibung wird ebenfalls eine Tabelle verwendet. Die Parameter der Funktion müssen mit den Parameternamen wie in der Deklaration in gleicher Reihenfolge mit einem "^" Tabellenzeichen eingefügt werden. Weitere Informationen werden mit dem "|" hinzugefügt.
| Par1 | Beschreibung zu diesem Parameter |
| Par2 | Beschreibung zu diesem Parameter |
| Weitere Informationen | und Beschreibungen zu oberem Parameter |
| Par3 | Beschreibung zu diesem Parameter |
Dies ist das Format wenn alle Funktionen zu einer Bibliothek in einer Datei gesammelt werden, das geht aber nur bei kleinen Bibliotheken mit nur wenigen Funktionen.
Die Überschriftebenen werden als Gruppierung verwendet.
====== Bibliothek.dll ======
===== Kategorie =====
==== Funktionsname ====
=== @Parameter ===
Dritten Ebene unter dem Funktionsnamen enthält eine Tabelle die Informationen zu dieser Funktion. Um die Informationen erkennen zu können erhalten sie ein Tabellenüberschriftszeichen "^" damit diese Zelle hervorgehoben wird. Alle Texte die nicht diese Schlüsselwörter enthalten, werden vom ApiHelper unter Notizen angezeigt.
| Deklaration | Declare-Deklarationssyntax. |
| Beschreibung | Kürze Beschreibung der Funktion. |
| Systeme | Funktion ist verfügbar in diesen Betriebsystemen, zB. (Win95; Win98; WinME; WinNT31; Win2000; WinXP) |
| Rückgabe | = Wert, wenn die Ausführung erfolgreich war.
= Wert, wenn die Ausführung fehlerhaft war. |
| Include | Zugehörige Deklarationen (Const/Enum/Type) die für diese Funktion notwendig sind. (Entspricht den Einträgen unter @Include.) |
| Beispiele | Verfügbare Beispiele zu dieser Funktion. (Entspricht den Einträgen unter @Beispiele.) |
In der Parameterbeschreibung wird ebenfalls eine Tabelle verwendet. Die Parameter der Funktion müssen mit den Parameternamen wie in der Deklaration in gleicher Reihenfolge mit einem "^" Tabellenzeichen eingefügt werden. Weitere Informationen werden mit dem "|" hinzugefügt.
| Par1 | Beschreibung zu diesem Parameter |
| Par2 | Beschreibung zu diesem Parameter |
| Weitere Informationen | und Beschreibungen zu oberem Parameter |
| Par3 | Beschreibung zu diesem Parameter |
Für die Deklarationen und Beispiele ist das Format ähnlich wie für Funktionspeschriebungen. Wie bei @Parameter wird für Schlüsselwörter ein @ hinzugefügt.
Die "Beispiel-Name" und "Deklarations-Name" können dann in den Funktionsdaten Tabelle eingetragen werden, und ApiHelper zeigt diese an. zB. Kann so ein Beispiel mit den Namen Dateifunktion mehreren Funktionen wie OpenFile und CloseFile usw verwendet werden. Gleiches gilt für Deklarationen.
====== Bibliothek.dll ======
===== @Beispiele =====
==== Beispiel-Name ====
<-- hier den Beispiel-Code einfügen
====== Bibliothek.dll ======
===== @Include =====
==== Deklarations-Name ====
<-- hier die Const/Enum/Type Deklarationen einfügen
