Introduction to the OS/2 API Documentation
by Prokushev, Daniel Lee Kruse, Anakor
Contents
Introduction
OS/2 and eComStation API not available for public domain. If for OS/2 users is only possible way to get API documentation via buying OS/2 Toolkit then eComStation users in better situation - OS/2 Toolkit shipped in the box. Anyway, OS/2 Toolkit documentation contain errors, not all API documented etc. Lot of parts just not included. eComStation comes with newer interfaces, but they not described in any eComStation official documentation.
In 1996 The OS/2 API project was started. But copyright issues not allowed to extend project after maintainers lost interest in it. So, all work from the OS/2 API project was never completed.
After EDM/2 was relaunched, in 2004 Daniel Lee Kruse started OS/2 API Documentation pages. Wiki provided good chance to make this project live.
This article describes how any API entry must be described.
API entry definition
Each API entry must be described and documented in common and standard representation form. Here is example of API function definition as used in the project ({this is comment}):
DosBeep {function name}
- DosBeep(frequency, duration)
- {function definition. No types described here}
Generates the specified frequency on the computer's speaker. {general function description}
Parameters
- frequency - ULONG - input
- {parameter description with type and stream direction}
Frequency as Hertz with valid values from 37 through 32767. {parameter description}
- duration - ULONG - input
Length of the sound in milliseconds.
Constants
None. {list of used constants}
Returns
NO_ERROR {list of return codes}
ERROR_INVALID_FREQUENCY
Module
DOSCALLS {name of export module}
Define (C/C++)
DOS_PROCESS {This entry optional and actual only for OS/2 Toolkit compatible C/C++ section. Controls include sequence}
Ordinal/Export name
286 {Ordinal and/or export name of function. Can be detected by LxLite, NeLite, etc.}
Calling convention
Cdecl32 {Calling convertion of function. Possible values are Cdecl32, Cdecl16, Pascal32 & Pascal16}
Example Code
Not needed for this example listing.
{Here example code. Preffered language - C. But various language-specific voodoo (like C/C++ += -= ++ --) must not used. Minimal pointers<->ULONG conversions because potential error points.}
Related Functions
WinAlarm {Link to related functions}
Comments
I don't have any. {Function specific comments}
OS Version Introduced
OS/2 2.1
Messages definition
Messages also can be interpreted as API entry. Usually you call API function WinSendMsg and receive the result. Each message has some specific parameters and return codes. So, message also must be represented in some form.
SOM Interface definition
SOM interfaces defined via the SOM Interface Definition Language. Module name not known all the time, so no module information. Calling convention is always Cdecl32.
Interface
interface WPShadow : WPAbstract { WPObject wpQueryShadowedObject(in BOOL fLock); BOOL wpSetShadowTitle(in PSZ pszNewTitle); BOOL wpSetLinkToObject(in WPObject FromObject); #ifdef __SOMIDL__ implementation { releaseorder: wpSetLinkToObject,withdrawn,wpSetShadowTitle,wpQueryShadowedObject; externalstem = wplink; local; externalprefix = shd_; majorversion = 1; minorversion = 2; filestem = wpshadow; metaclass = M_WPShadow; callstyle = oidl; dllname = "pmwp.dll"; wpQueryTitle: override; wpSetup: override; wpSaveState: override; wpRestoreState: override; wpQueryStyle: override; wpInitData: override; wpUnInitData: override; wpSetTitle: override; wpFilterPopupMenu: override; wpModifyPopupMenu: override; wpMenuItemSelected: override; wpViewObject: override; wpMenuItemHelpSelected: override; wpCreateFromTemplate: override; wpOpen: override; wpInsertPopupMenuItems: override; wpInsertMenuItems: override; wpCreateShadowObject: override; wpDragOver: override; wpDrop: override; wpQueryDefaultHelp: override; wpConfirmDelete: override; wpConfirmObjectTitle: override; wpPrintObject: override; wpFormatDragItem: override; wpDraggedOverObject: override; wpDroppedOnObject: override; wpQueryNameClashOptions: override; wpFilterMenu: override; wpModifyMenu: override; somDefaultInit: override; somDestruct: override; }; #endif /* __SOMIDL__ */ };
Comments
I don't have any.
OS Version Introduced
OS/2 2.1
Types definition
MyType {DataType Name}
My description
Type
List of the types fields, e.g.
ULONG oNextEntryOffset FDATE fdateCreation
C Declaration Method
One of the following:
- typedef
- typedef struct
- typedef const
- macro or #define
Fields
Explanation of the fields under type, e.g.
oNextEntryOffset Offset of next entry. fdateCreation Date of file creation.
Coment
Additional coments where applicable.
If anything in the type can't be done yet then leave a message in the talk page of the corresponding type, like this:
ToDo
Link to MB_OK can't be done yet
Constants definition
TRUE {Constant name }
Type
BOOL {Constant type}
Value
1 {Constant value}