Talk:OS2 API

Please don't make this available to the outside world just yet. I'm still considering layout and content for the opening page. Thanks. Daniel Lee Kruse

API definition format

How about describing API in an language-neutral format? I mean not in C notation but in something like SOM IDL? Because C API defination hard to read and some info missed (like ordinals and module names).

API def format

Language-neutral format is a good idea. Having never seen SOM IDL I have no idea what that would look like. Could you please post an example or two?

I had in mind that each API call would be a single page sectioned out. For example, the API call and its parameters, then a section with the parameters explained with constants listed - if any. Another section with example code. Maybe a section with closely related functions. A section detailing the return codes of that API call. Thanks. -Daniel Lee Kruse

Essentially that means an implementation like the docs coming with the toolkit?

Really, I mean definition of functions. At the present time C/C++ notation is used. As in header files. But such description has some disadvantager.

Function location not known (in which module function placed)
Ordinal or export name not known
Type and constant definition can be defined via #define -> without documentation impossible to predict is type or value defined
Impossible to convert to another language without human resources.

So, some language(programming)-neutral description seems to be good solution for above. // Prokushev

An example API function page

DosBeep

DosBeep(frequency, duration)
Generates the specified frequency on the computer's speaker.

Parameters

frequency - ULONG - input type
Frequency as Hertz with valid values from 37 through 32767.
duration - ULONG - input type
Length of the sound in milliseconds.

Constants

None.

Returns

NO_ERROR
ERROR_INVALID_FREQUENCY

Module

Need to find out.

Define

DOS_PROCESS

Ordinal/Export name

286 - I don't know the export name

Example Code

Not needed for this example listing.

Related Functions

Are there any?

Comments

I don't have any.
// End of example listing
Please edit to make more like what you had in mind. -Daniel Lee Kruse

Keyboard, mouse, video function list question

Should the mouse, keyboard, and video sections go under the control programming i/o section? Or maybe we ought to have an I/O section and place them there along with netlabs' usb api. -Daniel Lee Kruse

Most probably, we can create 2 sections. Highlevel Device I/O Function (Vio/Kbd/Mou) and low level Device I/O function (IOCtls) // Prokushev

Sounds great to me. -Daniel Lee Kruse