View source for Introduction to the OS/2 API Documentation

by [[Prokushev]], [[User:daniel.lee.kruse|Daniel Lee Kruse]], [[Anakor]]

== 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 [http://www.edm2.com/os2api/Various/Copyright.html 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 [[User:daniel.lee.kruse|Daniel Lee Kruse]] started [[OS2 API|OS/2 API Documentation]] pages. Wiki provided good chance to make this project live.

This article describes how eny 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 - [[OS2_API:DataType:ULONG|ULONG]] - input : {parameter description with type and stream direction}
Frequency as Hertz with valid values from 37 through 32767. {parameter description}
; duration - [[OS2_API:DataType:ULONG|ULONG]] - input :
Length of the sound in milliseconds.

==== Constants ====
None. {list of used constants}

==== Returns ====
[[OS2_API:CPI:error#NO_ERROR|NO_ERROR]]  {list of return codes}<br>
[[OS2_API:CPI:error#ERROR_INVALID_FREQUENCY|ERROR_INVALID_FREQUENCY]]<br>

==== 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 ====
[[OS2_API:WinAlarm|WinAlarm]] {Link to related functions}

==== Comments ====
I don't have any. {Function specific comments}

==== OS Version Introduced ====
OS/2 2.1<br> 

-----



== Messages definition ==

Messages also can be interpreted as API entry. Usually you call API function
[[OS2_API:WinSendMsg|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 [[Interface Definition Language]]. Module name not known all the time, so no module information. Calling convention is always [[Cdecl32]].
----

=== Interface ===
 interface WPShadow : [[SOM:Classes:WPAbstract|WPAbstract]]
 {
  [[SOM:Classes:WPObject|WPObject]] [[SOM:ObjectMethods:wpQueryShadowedObject|wpQueryShadowedObject]](in [[BOOL]] fLock);
  [[BOOL]] [[SOM:ObjectMethods:wpSetShadowTitle|wpSetShadowTitle]](in [[PSZ]] pszNewTitle);
  [[BOOL]] [[SOM:ObjectMethods:wpSetLinkToObject|wpSetLinkToObject]](in [[SOM:Classes:WPObject|WPObject]] FromObject);
 
 #ifdef __SOMIDL__
  implementation {
 
    releaseorder: wpSetLinkToObject,withdrawn,wpSetShadowTitle,wpQueryShadowedObject;
 
    externalstem = wplink;
    local;
    externalprefix = shd_;
    majorversion = 1;
    minorversion = 2;
    filestem = wpshadow;
    metaclass = [[SOM:Metaclasses:M_WPShadow|M_WPShadow]];
    callstyle = [[SOM:Call styles|oidl]];
    dllname = "pmwp.dll";               
 
    [[SOM:ObjectMethods:wpQueryTitle|wpQueryTitle]]: override;
    [[SOM:ObjectMethods:wpSetup|wpSetup]]: override;
    [[SOM:ObjectMethods:wpSaveState|wpSaveState]]: override;
    [[SOM:ObjectMethods:wpRestoreState|wpRestoreState]]: override;
    [[SOM:ObjectMethods:wpQueryStyle|wpQueryStyle]]: override;
    [[SOM:ObjectMethods:wpInitData|wpInitData]]: override;
    [[SOM:ObjectMethods:wpUnInitData|wpUnInitData]]: override;
    [[SOM:ObjectMethods:wpSetTitle|wpSetTitle]]: override;
    [[SOM:ObjectMethods:wpFilterPopupMenu|wpFilterPopupMenu]]: override;
    [[SOM:ObjectMethods:wpModifyPopupMenu|wpModifyPopupMenu]]: override;
    [[SOM:ObjectMethods:wpMenuItemSelected|wpMenuItemSelected]]: override;
    [[SOM:ObjectMethods:wpViewObject|wpViewObject]]: override;
    [[SOM:ObjectMethods:wpMenuItemHelpSelected|wpMenuItemHelpSelected]]: override;
    [[SOM:ObjectMethods:wpCreateFromTemplate|wpCreateFromTemplate]]: override;
    [[SOM:ObjectMethods:wpOpen|wpOpen]]: override;
    [[SOM:ObjectMethods:wpInsertPopupMenuItems|wpInsertPopupMenuItems]]: override;
    [[SOM:ObjectMethods:wpInsertMenuItems|wpInsertMenuItems]]: override;                                                
    [[SOM:ObjectMethods:wpCreateShadowObject|wpCreateShadowObject]]: override;
    [[SOM:ObjectMethods:wpDragOver|wpDragOver]]: override;
    [[SOM:ObjectMethods:wpDrop|wpDrop]]: override;
    [[SOM:ObjectMethods:wpQueryDefaultHelp|wpQueryDefaultHelp]]: override;
    [[SOM:ObjectMethods:wpConfirmDelete|wpConfirmDelete]]: override;
    [[SOM:ObjectMethods:wpConfirmObjectTitle|wpConfirmObjectTitle]]: override;
    [[SOM:ObjectMethods:wpPrintObject|wpPrintObject]]: override;
    [[SOM:ObjectMethods:wpFormatDragItem|wpFormatDragItem]]: override;
    [[SOM:ObjectMethods:wpDraggedOverObject|wpDraggedOverObject]]: override;
    [[SOM:ObjectMethods:wpDroppedOnObject|wpDroppedOnObject]]: override;
    [[SOM:ObjectMethods:wpQueryNameClashOptions|wpQueryNameClashOptions]]: override;
    [[SOM:ObjectMethods:wpFilterMenu|wpFilterMenu]]: override;                                                     
    [[SOM:ObjectMethods:wpModifyMenu|wpModifyMenu]]: override;                                                     
    [[SOM:ObjectMethods:somDefaultInit|somDefaultInit]]: override;          
    [[SOM:ObjectMethods:somDestruct|somDestruct]]: override;             
 
  };
 #endif /* __SOMIDL__ */
 };

=== Comments ===
I don't have any.

=== OS Version Introduced ===
OS/2 2.1<br>
----

== Types definition ==
=== MyType {DataType Name} ===

My description

==== Type ====
 
List of the types fields, e.g.
 [[OS2 API:DataType:ULONG|ULONG]]  oNextEntryOffset
 [[OS2 API:DataType:FDATE|FDATE]]  fdateCreation
 
===== C Declaration Method =====

One of the following:
* typedef
* typedef struct
* macro

==== Fields ====

Explanation of the fields under type, e.g.

 oNextEntryOffset   Offset of next entry.
 fdateCreation      Date of file creation.

==== Coment ====

Additional coments where applicable.
-----

== Constants definition ==
=== [[OS2_API:Constant:TRUE|TRUE]] {Constant name }===
==== Type ====
[[OS2_API:DataType:BOOL|BOOL]] {Constant type}
==== Value ====
1 {Constant value}
----