This header file defines various types and other symbols for defining and using COM interfaces. Most of these symbols correspond directly to similar symbols in the Win32 API; however, all of the names are prefixed with oskit_ to avoid conflicts with actual Win32 headers or other symbols used in the client OS environment, and they are named according to the standard OSKit conventions for consistency with the rest of the OSKit.The oskit_guid structure and corresponding type oskit_guid_t define the format of DCE/COM globally unique identifiers:
oskit_u32_t data1; /* Data - often time stamp */ oskit_u16_t data2; /* Data */ oskit_u16_t data3; /* Data */ oskit_u8_t data4[8]; /* Data - often MAC address */};Additionally, the related preprocessor macro OSKIT_GUID can be used to declare initializers for GUID structures.
The type oskit_iid_t is defined as an alias for oskit_guid_t, and is specifically used for COM interface identifiers (IIDs).
The following preprocessor symbols are defined for constructing and testing COM error codes:
- OSKIT_SUCCEEDED
- Evaluates to true if the error code parameter indicates success (the high bit is zero).
- OSKIT_FAILED
- Evaluates to true if the error code parameter indicates failure (the high bit is one).
- OSKIT_ERROR_SEVERITY
- Extracts the the severity (success/failure) flag from the supplied error parameter.
- OSKIT_ERROR_FACILITY
- Extracts the the facility code (bits 16-30) from the supplied error parameter.
- OSKIT_ERROR_CODE
- Extracts the the code portion (low 16 bits) of the supplied error parameter.
- OSKIT_S_OK
- Defined as zero, the standard return code for COM methods indicating ``all's well, nothing to report.''
- OSKIT_S_TRUE
- Defined as zero, the same as OSKIT_S_OK; this is used when the method returns a true/false flag of some kind on success.
- OSKIT_S_FALSE
- Defined as one (which, as a COM error value, still indicates success); used when the method returns a true/false flag of some kind on success. Note that this representation is exactly reversed from normal C conventions for boolean flags; it's a unfortunate inherited Microsoftism.
Finally, the following macros, whose exact definitions are compiler-specific, are used in declarations of functions and function pointers for COM interfaces, to ensure that the standard COM calling conventions are used:
- OSKIT_COMCALL
- Declares a function to use standard COM calling conventions, known as stdcall conventions in the COM specification. This tag must be placed in the function prototype between the return value and the symbol being declared, e.g., oskit_error_t OSKIT_COMCALL query(...). (Note that the GNU C compiler also allows the tag to be placed at the end of the prototype, but this placement is not compatible with other compilers and therefore not recommended.)
- OSKIT_COMDECL
- This is simply a shorthand for oskit_error_t OSKIT_COMCALL; it is used in declarations of normal COM methods which return an error code as the result.
- OSKIT_COMDECL_U
- This is simply a shorthand for oskit_u32_t OSKIT_COMCALL; it is generally used in declarations of the addref and release methods common to all COM interfaces, which return integer reference counts as their result.
- OSKIT_COMDECL_V
- This is simply a shorthand for void OSKIT_COMCALL; it is used in declarations of COM methods having no return value.