Yep, take for example this gem:
ODMActivate
ODMSTATUS ODMActivate (ODMHANDLE handle, WORD action,
LPSTR lpszDocId)
This function causes the DMS to perform actions that do not require cooperation
from the calling application. Control is returned to the calling application after
the specified action has been completed, except where noted. A DMS is not
required to support all of these actions.Parameters:
handle- in - A handle obtained by a previous ODMRegisterApp call.
action- in - One of the following action codes:
- ODM_NONE- No specific action is requested. The DMS should
simply make itself visible and let the user select the action to
be performed.- ODM_DELETE- The DMS should delete the specified document.
Note that most DMSs will not allow a deletion to occur if the
document is currently in use.- ODM_SHOWATTRIBUTES- The DMS should display the
specified document’s profile or attributes.- ODM_EDITATTRIBUTES- The DMS should display the specified
document’s profile or attributes, and the user should be put
in edit mode. Note that some DMSs will not allow a
document’s attributes to be edited while it is in use.- ODM_VIEWDOC- The DMS should display the specified
document in a viewer window. The DMS may return control
to the calling application before displaying the document.- ODM_OPENDOC- The DMS should open the specified document
in its native application. The DMS may return control to the
calling application before displaying the document. This
function is intended for use by applications other than the
document’s native application (e-mail, workflow, annotation,
etc.). Applications should use ODMOpenDoc to access
their own documents. If this function fails, the calling
application may wish to retry using the ODM_VIEWDOC
action code.- ODM_NEWDOC - The DMS should allow the user to create and
save a new document. Optionally the caller can specify a
template document in lpszDocId. If lpszDocId is Null the
DMS should allow the user to choose the file format of the
document to be created and the document template. In
most cases it is expected that the DMS will need to launch
an application to create the document. The DMS may return
before satisfying this call, in which case the calling
application will not get notification when the new document
has been created. The user is free to cancel this function.- ODM_CHECKOUT - The DMS should check-out/reserve the
document for the current user. The DMS can display
whatever UI it might use for document check-out. This
action allows the user to explicitly reserve a document in the
DMS in a way that is persistent across ODMA or DMS
sessions. ODMOpenDoc should be used to get the content
file. See ODMCloseDoc and ODMCloseDocEx for
recommendations on how to handle closing a document that
was explicitly reserved before it was opened.- ODM_CANCELCHECKOUT - The DMS should cancel a previous
checkout/reserve on the document, if it has been checked
out by the current user. The DMS can display whatever UI it
might use for canceling a document check-out.- ODM_CHECKIN - The DMS should check-in/unreserve the
document if it’s checked-out by the current user. The DMS
can display whatever UI it might use for document check-in.
ODMSaveDoc or ODMSaveDocEx should already have
been used, if necessary, to save the content to the DMS.
ODM_SHOWHISTORY - The DMS should display the specified
document’s history (i.e. revisions, events, activities, etc.).
lpszDocId - in - A document ID specifying the document on which to
perform the requested action. This parameter may be Null if the action is
ODM_NONE or ODM_NEWDOC. If action is ODM_NEWDOC the
application can specify the document ID of a template document.
Return value:- ODM_SUCCESS if successful.
- ODM_E_DOCID if the document ID is invalid or refers to a document
that no longer exists.- ODM_E_INUSEif the document is currently in use or checked-out by
another user on actions where this would preclude the
operation from completing correctly.- ODM_E_ACCESS if the user doesn’ t have appropriate access rights
to perform the requested action (i.e. check-out or check-in the
document).- ODM_E_OFFLINE if the DMS cannot currently access the document
because the user client is off-line.- ODM_E_ARCHIVED if the DMS cannot currently supply the document
content because it has been archived.- ODM_E_CANCEL if the action was canceled by the user.
- ODM_E_NOSUPPORT if action is not supported by the DMS.
- ODM_E_ITEM if action is invalid or not supported by the DMS.
- ODM_E_FAIL if the action could not be completed by the DMS.
- ODM_W_NOACTION if action is ODM_CHECKOUT and the
document is already checked-out/reserved by the current user.
This status can also be returned if action is either
ODM_CANCELCHECKOUT or ODM_CHECKIN and the
document is not currently checked-out/reserved by any user.- ODM_E_HANDLE if handle was invalid.
And so, to properly present this out, after enumerating the type, you need to do
Function ODMActivate(
the_odmHandle : ODMHANDLE; -- autogen type, remember to isolate these from leaking
action : minwindef_h.WORD, -- autogen type, remember to make sure sizes are correct
lpszDocId : winnt_h.LPSTR -- autogen type, remember to make sane translation
) return ODMSTATUS
with Export, Convention => C, External_Name => "ODMActivate",
Pre => Interfacing.Action'(+action) in NONE | DELETE | SHOWATTRIBUTES |
EDITATTRIBUTES | VIEWDOC | OPENDOC | CHECKOUT | CANCELCHECKOUT |
CHECKIN,
Post => +ODMActivate'Result in SUCCESS | DOCID | OFFLINE | TRUNCATED |
Interfacing.ITEM | NOSUPPORT | HANDLE;
And that’s just one function-call, and this isn’t factoring out the various inputs/outputs into types and subtypes… you want a good tool, make one that can read API-specs like this and generate the appropriate types and subtypes, the appropriate subprogram headers… make one that can ingest OpenGL and spit out a reasonable, correct, complete thick Ada binding.
But the C way is “document” “everything” and force the consistency-checking onto the user/implementer… because “simple”.
No, the drivers are what interfaces into the hardware. It matters not what they are written in so long as they (a) correctly access/operate the hardware, and (b) correctly interface into the host OS — but you’ve illustrated exactly how C cripples software engineering: you confused the OS’s implementation-language with what is usable, and what is usable with what is suitable, and both of those with what is most convenient right-here/right-now, labeling it as “natural”.
Do you see it?
(Besides, this gets to a decades-long sore spot of mine: C is not the best/only[-real] OS-dev language. In the Burroghs it’s Algol, in most pre-Windows OSes it’s assembly for that particular architecture, for the original Mac it was Pascal, for VMS it was literally “what makes the most sense” thanks to their common-language environment.)
I have very mixed feelings about that.
