This following reference documentation describes API based on Microsoft Interface Definition Language (MIDL). A brief overview of the naming, types, and error-handling conventions will be presented.
Technical Note: These API are for review and comment only. There is no guarantee of correctness. This specification approximates the intended direction of the final API.
The naming convention for the IDL specification uses the notation of separating words with CapitalLetters. (This release removed all the "_" and used concatenation of Capital letters to distinguish words.) The following conventions are being followed.
Module File Name : same as module name with .idl
#define for constants : entire name in UPPER CASE interface
name & declaration : CapStyle with beginning I interface
/variable instance : smallCapStyleAgain
method arguments : smallCapStyleAgain
general method signature : nameCapStyle
query parameter : getParameterName
assignment : setParameterName
state query : isStateName
Hungarian notation with a a classifying prefix has been applied to most (but not necessarily all) variable declarations and method arguments. In this case, d_VariableName would indicate a double variable. dp_VariableName would indicate a pointer to a double variable. Note, C++ function declarations need parameter types but not parameter names, however, IDL requires both.
The use of get and set methods on these attributes, since IDL does not produce a get/set prefix to the methods. This will not work for non-IDL-like systems.
Each Interface method signature returns one or more status codes according to the Microsoft COM specification, wherein nearly every COM API interface member function returns a value of the type HRESULT. COM uses a naming convention for different HRESULT success and error codes. Any name with S_, as in S_TRUE, S_FALSE, or STG_S_CONVERTED, means that the function succeeded. Any name with E_ in it, which may be at the beginning as in E_FAIL or RPC_E_NOTCONNECTED means that the function failed. The most common codes are listed in the following table:
| Value | Meaning |
| S_OK | Function succeeded. Also used for functions that semantically return a Boolean TRUE result to indicate that the function succeeded. |
| S_FALSE | Used for functions that semantically return a Boolean FALSE result to indicate that the function succeeded. |
| E_NOINTERFACE | QueryInterface did not recognize the requested interface. |
| E_NOTIMPL | Member function contains no implementation. |
| E_FAIL | Unspecified failure. |
| E_OUTOFMEMORY | Function failed to allocate necessary memory. |
A type defines a data representation and can be fundamental or derived. MIDL includes most fundamental types. The number and variety of derived types is limitless, but the more type checking a system performs the better the potential of correctness. The OMAC API contains a Data Representation IDL covering basic data types expected of the controller domain, e.g., Transform Matrix. At this point, these type definitions are merely a placeholder. In the future, full integration with STEP Part 41, "Integrated Generic Resources: Fundamental of Product Description and Support," that contains a specification for measures and units. However, issues of performance and specifying compliant types via IDL remain to be resolved.
Source Directory