miser
|
oMiser Technical Note m110400
MOb API |
orcmid.github.io>
miser> oMiser> m110400c> 0.0.2 2026-02-27T18:01Z |
The MOb provides access to identifiable obs, whether intrinsic primitives, ones introduced as lindies, binding-name values, or derived individuals (synthetics) produced by applicative-operation extensions.
- 1. Establishing oMiser and the MOb
- 2. Simplified Interfaces
- 3. Strings vs. BSTR
- 4. oFrugal Decoupling
- 5. The Friendly API
1. Establishing oMiser and the MOb
The initialization of an oMiser instance involves establishment of the
initial MOb. This is accomplished with the omEstablish procedure,
HRESULT omEstablish( const CLSID* omClassID, const IID* riid,
void **ppvObject );
defined in the oMiser header files “oMiser-Win32.h” and “oMiser-Win32.hpp”
for C and C++, respectively. This is the oMiser-specialized counterpart of a
COM class factory for the MOb.
The supported omClassID values are defined in the header files for the
current oMiser version. The practice is to support earlier Class IDs until
breaking changes make that infeasible.
The riid parameter must be for IUnknown or IMOb.
2. Simplified Interfaces
An established MOb permits simplified interface helpers because there is always one and only one established MOb. This allows helper operations with simplified parameters. For example,
HRESULT omGetLindy(const char[] id, void **ppvIOb);
Is a friendlier version of the C Language
HRESULT ppvIMOb->pv->GetLindy(ppvIMOb, const char[] id, void **ppvIob);
and the equivalent C++ Language
HRESULT ppvIMob->GetLindy(const char[] id, void **ppvIob)
where, in the friendly case, a ppvIMOb is held privately and usable by the set of friendly versions automatically. The friendly versions are the same for both C and C++. The results are still COM Interface pointers, but for Iob interfaces.
There is an additional HRESULT defined for the case that there has been no
successful omEstablish before a friendly operation is attempted.
3. Strings vs. BSTR
Officially, strings of characters must be in BSTR (Unicode UTF16-LE) form
for correct use in COM interfaces. The difficulty of BSTR for oMiser is
with the high incidence of wide (16-bit) character codes with many 0 bits.
This does not work well for hashing of identifiers.
UTF8 strings are used in the oMiser API to facilitate hashing and also economize on storage in US and Western European settings. The trade-off will be reviewed after there is more experience and good statistics between UTF8 and UTF16-LE (BSTR) coding of identifiers used with oMiser and oFrugal.
In the determination of identifier length, each code point, regardless of its length in UTF-8, counts as one character. Whether the Standard C Language allowance for identifiers of up to 63 characters is tolerated, the practice of truncating longer identifiers, if implemented, will lead to oMiser warnings.
It might also be possible to adjust hashing to deal with a high incident of recurring 0x0 and similar bytes and even neutralize idetifier hashes by having them always conducted on UTF-32 code points. That is very speculative for now.
4. oFrugal Decoupling
Although the primary oMiser application is oFrugal, the API is simplified by not enforcing any particular constraints that should, ideally, be handled by the application, whether oFrugal or another usage.
Applications, including oFrugal, are expected to filter and correct the identifiers they employ. For example, for omGetPrimitive it is up to the application to include the leading “.” and capitalize the primitive name (e.g., .ARG instead of .arg or any other mixing of cases). There are similar considerations with respect to binding names. Inclusion of the ^-prefix is valuable to avoid collisions with lindies (which result in errors in either conflict) but oMiser does not fully verify identifier syntax.
5. The Friendly API
HRESULT omGetPrimitive(const char[] id, void **ppvIOb);
// return the primative individual for the specified .-prefixed
// id string. If there is no such individual, a ?.-form lindy
// is the result and the HRESULT is an exception success value.
HRESULT omGetLindy(const char[] id, void **ppvIOb);
// return the lindy individual for the specified lindy id.
// If there is a conflicting non-lindy named entry, the conflict
// will be reported as a failure. If there is no entry,
// one will be created.
HRESULT omSetBinding((const char[] id, const void *pvIOb));
// set the identified binding to have the supplied object as
// the binding value. It is recommended to use a distinct
// prefix, such as oFrugal's '^', to avoid conflict with lindies.
// If there is a conflict with an used identifier that is not
// for a binding, a failure result is returned and the binding
// is not established.
HRESULT omGetBinding(const char[] id, void **ppvIOb);
// return the value defined for the identified binding. If
// there is no such binding, NULL is returned and an error
// HRESULT reported.
HRESULT omGetVersion(int semver[3])
// return a semantic version major, minor, patch triple value for the
// version of oMiser being operated. There is no semver suffix
// provision.
size_t omGetTitle_s(char szTitle[], size_t maxTitle);
// deliver a descriptive title to the szTitle[] array, not exceeding
// maxTitle characters including the terminal '\0'. A typical title
// is "oMiser 0.0.0 (spitball)". The number of characters transferred
// is returned. Titles taking more than maxTitle chars will be
// truncated to maxTitle characters, including a final '\0'.
// a result of 0 indicates that no transfer occured and there may
// be a defect in the parameters.
I invite discussion about Miser Project topics in the Discussion section. Improvements and removal of defects in this particular documentation can be reported and addressed in the Issues section. There are also relevant projects from time to time.
|
You are navigating the Miser Project on Github |
created 2026-02-25 by orcmid |