From: Subject: AIIM Standards Date: Fri, 7 Apr 2000 09:28:42 -0700 MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_NextPart_000_0040_01BFA073.AA5BF660"; type="multipart/alternative" X-MimeOLE: Produced By Microsoft MimeOLE V5.00.2919.6600 This is a multi-part message in MIME format. ------=_NextPart_000_0040_01BFA073.AA5BF660 Content-Type: image/gif Content-Transfer-Encoding: base64 Content-Location: http://www.aiim.org/images/standards/header_standards1.gif R0lGODlhKgM6APf/AP///yEhIUJCQlpaWmNjY87Ozvf394yEhL2lpZyEhLWMjEIxMSEYGIxaWlo5 OXtKSoxKQoxaUntKQntSSpRza3taUrVjSq1aQoxaSqVaQsacjJxjSqVzWmtKObVzUqVrSsZ7UpRa ObVrQs61pd6UY5RSKd69pWNKOcaljHNSOeecY9aMUueUUpRrSvelY96UUv+lUv/375yUjN7GrZSE c+fGpda1lDEpIb2ce+e9lK2Ma3taOVpCKZRrQmMxAO/n3s7Gvf+tUu/Opd69lLWUa5yEY+e9hHtj QkI5KefGjOe9c5xjAL21pd7Orc61hK2UY9a1c8alY62MSpxrCEoxAGNCAHtSAJRjAK2llLWUSqV7 Ida1Y8alUqWEMZxzEO/nzufevc61UpSMSnNza0pKQqWle4yUUq21lHuUUpS1hHOlWmulY6WtpZyl nHOEc63GrWOlY1J7WoytlFKca3OtjEJ7WkKMazljUnOMhFp7c73GxpytraW9vYylpXuUlFKMjAgQ EDFzcyFraxhrazmEjClrcyljaxhaYylaYzFaYylzhBh7lDGEnCl7lHO91lqElEqEnFqtzimErRBC WhhznFp7jDlrhDmMtSk5QkqUvXOlxjl7pRhahGOUtSFCWjFrlFJzjIStzmuUtXOlzjlrlEJ7rSla hCljlCFSexgpOc7W3py1zikxOVp7nBgxSkprlCFCa4ylxlpzlFJrjDFCWkJaezlajGuErSExSjFK c0JKWoSUtVJjhBgpWkJKa0JKeykxYxghUt7e57W1vXt7hMbG1rW1znNzhJyctaWlxnt7nBgYITk5 Wjk5YxgYMRAQMSkhUhgQQiEYQoyEnHtrlFpKc5yUpTkpSiEYKVIxY0IxSnNKhJx7pWtCc4RzhLWU tSkhKZRjlIRShJRalDkhOWs5a2spY62EpXs5a2sxWlohSmsYUntKa1pKUrWUpVo5SkIhMYRKY2sp QnNaY86ttWtKUsacpb2UnK2EjFoxOWs5QntKUnNCSnM5QmsxOQAAACwAAAAAKgM6AEAI/wB9+FhC sKDBgwgTKlzIsKHDhxAjSpxIsaLFixgzatzIsaPHjyBDihxJMmMVK1auXCnJsqXLlwIJrpRZcOYS mzhr6qTJ8+ZOnz1zBv0pFKjRokiJKh3K9OhSp02TRn0qFarVqlipap3K9epWr12zhv0qFqzZsmjJ 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 ------=_NextPart_000_0040_01BFA073.AA5BF660 Content-Type: multipart/alternative; boundary="----=_NextPart_001_0043_01BFA073.AA5BF660" ------=_NextPart_001_0043_01BFA073.AA5BF660 Content-Type: text/html; charset="Windows-1252" Content-Transfer-Encoding: quoted-printable Content-Location: http://www.aiim.org/industry/standards/index.html AIIM Standards ------=_NextPart_001_0043_01BFA073.AA5BF660 Content-Type: text/html; charset="Windows-1252" Content-Transfer-Encoding: quoted-printable Content-Location: http://www.aiim.org/industry/standards/index_head.html AIIM Standards
3D"AIIM
------=_NextPart_001_0043_01BFA073.AA5BF660-- ------=_NextPart_000_0040_01BFA073.AA5BF660 Content-Type: text/html; charset="Windows-1252" Content-Transfer-Encoding: quoted-printable Content-Location: http://www.aiim.org/odma/odma20.htm ODMA 2.0 Specification =20
Open Document=20 Management API

Version 2.0
September 19, 1997

To download the developer's kit, please fill out the registration form = and then=20 download.=20

ODMA HOME = PAGE=20



*Before downloading this file, a registration form = must be=20 submitted.=20


Download ODMA=20 2.0 .zip file -- This updated file (as of = 5/11/98)=20 contains source code of a sample DMS and sample application, header = files and=20 libraries for build apps and the ODMA 2.0 specification. New=20

Download=20 Specification -- MS Word version of the specification.=20

Overview

ODMA = API

  • ODMActivate =
  • ODMCloseDoc =
  • ODMCloseDocEx<= /A>=20
  • ODMGe= tAlternateContent=20
  • ODMGetDMS=20
  • ODMGetDMSCoun= t=20
  • ODMGetDMSInfo =
  • ODMGetDMSList<= /A>=20
  • ODMGetDocInfo =
  • ODMGetDocR= elation=20
  • ODMGetLead= Moniker=20
  • ODMNewDoc=20
  • ODMOpenDoc=20
  • ODMQueryC= apability=20
  • ODMQueryClose<= /A>=20
  • ODMQueryExec= ute=20
  • ODMQueryG= etResults=20
  • ODMQueryIn= terface=20
  • ODMRegisterAp= p=20
  • ODMSaveAs=20
  • ODMSaveAsEx= =20
  • ODMSaveDoc
  • ODMSaveDocEx=20
  • ODMSelectDoc=20
  • ODMSelectDocE= x=20
  • ODMSe= tAlternateContent=20
  • ODMSetDMS=20
  • ODMSetDocEven= t=20
  • ODMSetDocInfo<= /A>=20
  • ODMSetDocR= elation=20
  • ODMUnRegist= erApp=20

DMS=20 Interface

  • ODMGetODM= Interface=20
  • IODMDocMan=20 Interface=20
  • IODMQuery=20 Interface=20
  • IODMDocMan2=20 Interface

Binding to the=20 API

Installing a=20 DMS

  • Windows=20 3.x, Windows 95 and Windows NT

Installing a=20 Client Application

Connection=20 Manager Trace Logging

Appendix=20 A

  • Document=20 Attributes

Appendix=20 B

  • Preferred=20 Call Usage for Initial File Creation

Revision History=20

Version 1.0 - with small BHC-325 at the end of the document Brad = Clements,=20 SoftSolutions. This is the original version.
Version 1.0 - with = small=20 DM1\285 at the end of the document Mike Gardiner, Novell. This = contains=20 additional information for registering ODMA under Windows 95 and NT. = It also=20 adds a new table for document ID constants.
Version 1.0a
Rod = Schiffman,=20 Novell. Additional information on the ODMA spec background, usage of = calls,=20 suggestions on the use of document ID character sets and the addition = of=20 ODM_E_INUSE as a valid return code in ODMActivate.
Version = 1.5
Jerry=20 (Gerald) Willett, PC DOCS, Inc. Added the Query specification. This = included=20 the Query Syntax and Query Examples sections and the ODMQuery* = functions and=20 the IODMQuery COM interface. Also added a clarification to the = expected=20 behavior of an application when calling ODMSaveAs and an empty string = is=20 returned for lpszNewDocId.
Version 2.0
Bob St.Jean, Digital = Equipment=20 Corp. Added additional attributes and functions to improve ODMA = support for=20 popular Document Management System (DMS) features. These are mostly = defined in=20 a new IODMDocMan2 interface. Defined several items to help provide = better=20 out-of-the-box integration between desktop applications and DMS. Also = added=20 clarifications to the existing specification and arranged the = functions=20 alphabetically.

Overview=20

The original impetus for the Open Document Management API (ODMA) = was the=20 recognition that there was no standard method for a client application = to=20 integrate with a Document Management System (DMS). Each DMS vendor = wrote=20 separate integration code for each of the major client applications = they=20 supported. Applications that did not have integrations written for = them by the=20 DMS vendors would have to write and support a separate integration for = each=20 DMS that was supported. This required a complete matrix of = integrations, each=20 with its own set of bugs, limitations and reliability issues. It = seemed=20 obvious that a high level standard for connecting applications and = document=20 management systems was a natural fit.=20

A small group of application and DMS vendors started working = together to=20 create an API that would allow applications and document management = systems to=20 inter-operate through a single high level API. This implied the = creation of a=20 standard, however, the creation of a standard has many pitfalls. = Probably the=20 biggest problem is that a lot of work can be put into the creation of = the=20 standard, and nobody uses it.=20

The industry is filled with examples of standards that were = obsolete by the=20 time they made it through the standardization process. By the time = some=20 standards make it through the standardization process, they are so = large and=20 unwieldy they are almost impossible to implement and maintain. Company = politics and hidden agendas of the participants can play as big a role = in the=20 adoption of a standard as trying to solve the problem in the first = place. The=20 industry is also full of proprietary API=92s that claim to be = standards, but are=20 not. The initial group of vendors that met and formed the ODMA = consortium=20 wanted to avoid as many of these problems as possible.=20

The working rules of the ODMA consortium are fairly = simple.

  1. If the standard does not solve a problem it will not be used.=20
  2. If the creation of the standard takes a long period of time, it = does not=20 solve the problem.=20
  3. If the standard is difficult to implement, it does not solve the = problem.=20
  4. The standard must be vendor independent.=20
  5. The standard must not try to solve all vendors=92 problems, or = it will be=20 big, complex and take a long time to implement. This violates rules = 1, 2 and=20 3 above.=20
  6. It is the customers that lose if there is not a straightforward = way to=20 integrate applications that create documents and applications that = manage=20 documents.=20
  7. Easy integration between applications and document management = systems=20 will grow the industry and increase sales for the entire = marketplace.=20

It is difficult to express the importance the initial members of = the=20 consortium placed on wanting to create a useful API that is vendor and = platform independent while still simple to implement. They recognized = that=20 they could solve 80 percent of the problem easily and were willing to = live=20 with having to solve another 10 percent over time and probably never = being=20 able to solve the final 10 percent.=20

The Open Document Management API (ODMA) is a standardized, = high-level=20 interface between desktop applications and document management systems = (DMSs).=20 Its purposes are:

  1. To make DMS services available to users of desktop applications = in a=20 seamless manner so that these services appear to the user like = extensions of=20 the applications.=20
  2. To reduce the application vendors burden of having to deal with = multiple=20 DMS vendors. By writing to ODMA, an application vendor has = potentially=20 integrated his application with all supporting DMSs.=20
  3. To reduce the DMS vendors burden of integrating with multiple=20 applications. By supporting ODMA a DMS vendor has potentially = integrated=20 with all applications that have written to ODMA.=20
  4. To reduce effort and complexity needed to install and maintain = DMSs.=20

ODMA specifies a set of interfaces that applications can use to = initiate=20 actions within a DMS. The API is intended to be relatively easy for=20 application vendors to incorporate into updates of existing = applications. It=20 should not require major restructuring of an application to integrate = it with=20 ODMA. Note that this version of ODMA does not specify how DMSs may = initiate=20 actions within the applications.=20

The ODMA API is platform-independent. The associated data type = definitions=20 and binding information are platform-specific. Currently, most of the = work has=20 been done in Windows. It makes this document look Windows specific, = but over=20 time, the platform specific entries for other platforms will be added = as they=20 are defined.=20

Document IDs

Many of the ODMA functions accept or return a Document ID = parameter. A=20 document ID is a persistent, portable identifier for a document. It = can be=20 stored and used in a later session, and it can be passed across = platforms via=20 email or other processes.=20

A Document ID is a case insensitive, null-terminated string of = printable=20 characters. Although a document ID is case insensitive, an application = should=20 never change the case of a document ID. The format of a document ID is

::ODMA\DMS_ID\DM_SPECIFIC_INFO

The DMS_ID portion of a document ID will identify which DMS = provided the=20 ID. This information is primarily for the use of ODMA itself; = applications=20 using ODMA should not need to know which DMS provided a particular ID. = The=20 ODMA group members will coordinate these IDs to ensure their = uniqueness. The=20 maximum length of the DMS_ID portion of the document ID is specified = by the=20 constant ODM_DMSID_MAX. The DM_SPECIFIC_INFO portion of the ID = will=20 vary depending on which DMS built the ID. The total length of the = document ID=20 including the terminating Null character cannot exceed = ODM_DOCID_MAX=20 bytes.=20

ODMA-aware applications should be able to handle a document ID = anywhere=20 they handle an externally-generated document filename. For example, if = the=20 application allows a document filename to be passed as a command line = argument=20 then it should allow a document ID to be passed in the same way. If = the=20 application allows document filenames to be used in DDE commands then = it=20 should also support the use of document IDs in the same commands.=20

Although the technical definition of a document ID is a case = insensitive,=20 null-terminated strings of printable characters , there are some = general rules=20 that are more likely to make a DMS and ODMA application work better = together.=20 ODMA was designed so that it would be easy to add to an application = without=20 major modifications in code or structure. If a DMS passes a document = ID that=20 breaks fundamental rules of normal file and path names it will = probably run=20 into problems if it is passed in on a command line. Special characters = like ^,=20 [, ], |, *, -, >, < and ? are processed by the UNIX shell even = before=20 they are seen by the application. It is possible to pass these = characters by=20 using special escape sequences, but that places a burden on the DMS = vendor to=20 process the document ID before giving it to the ODMA application. Some = operating systems require the application to handle the reverse = process of=20 interpreting and removing the escape characters. The application may = be able=20 to support the escape removal on the command line, but not if the = document ID=20 with escape characters is returned in a procedure call. In most cases, = it is=20 easier to generate a document ID that contains a fairly simple set of=20 characters. The following table suggests characters it may be wise to = avoid=20 for different platforms.

Platform Characters to = avoid
Windows 3.x " =91 < > * ? | = and the space=20 character
Windows 95 " =91 < > * ? | =
Other platforms to be = defined

Constants

The following table lists the constants that are defined in the = odma.h=20 header.
CONSTANTS Win 3.x Win32 Mac UNIX Other
ODM_DOCID_MAX
Maximum=20 length of a document ID including the null-terminator.		   80   255   255   255 255
ODM_FILENAME_MAX
Maximum=20 length of a path/filename returned by ODMA including the = terminating=20 Null character. 		  128   255   255   1024 255
ODM_API_VERSION
The=20 version of the ODMA API to which this header file corresponds. = See=20 ODMRegisterApp. 		  200   200   200   200   200
ODM_DMSID_MAX
Maximum=20 length of a DMS ID including the null-terminator.		   9   9   9   9   9
ODM_APPID_MAX
Maximum=20 length of an Application ID including the null-terminator.		   16   16   16   16   16
ODM_FORMAT_MAX
Maximum=20 length of a content format string including the = null-terminator.		   81   81   81   81   81
ODM_QUERYID_MAX
Maximum=20 length of a query ID string including the null-terminator.		 255 255 255 255 255 =

Error Handling

Nearly all of the ODMA functions use the return value to indicate = to the=20 calling application whether the function succeeded, failed because the = user=20 canceled the operation, or failed for other reasons. The DMS is = responsible=20 for displaying informational error messages to the user where = appropriate=20 except when the ODM_SILENT flag is specified. The DMS must take = care to=20 return the appropriate error indication because applications may act=20 differently depending on whether an ODMA call was canceled by the user = or=20 failed for other reasons. The calling application generally should not = display=20 error messages when an error value is returned from ODMA unless the=20 ODM_SILENT flag was specified.

Connections and the ODMA = Connection=20 Manager=20

The ODMA connection manager is a small software module that sits = between=20 applications using ODMA and document management systems implementing = ODMA. It=20 manages the connections between these components and routes ODMA calls = to the=20 appropriate provider. A freely redistributable copy of the ODMA = connection=20 manager will be provided to any vendor wishing to implement or make = use of the=20 ODMA API. This is a place where it would be possible to provide = mapping code=20 that would allow ODMA to have truly platform independent document IDs, = however, it currently only manages connections and does not touch = document=20 IDs.

Document Format Names=20

When new documents are registered with a DMS via ODMA and when an = existing=20 document's format is changed by an application, the application passes = a=20 document format name to ODMA. Document format names are = null-terminated=20 strings defining the format of a document's content. These strings = have a=20 maximum length defined by the ODM_FORMAT_MAX constant.

There are several places in ODMA where a content format name for a = document=20 can be specified or requested. The ODMNewDoc, ODMSaveAs = and=20 ODMSaveAsEx functions each have a lpszFormat parameter where a = format=20 can be specified. The ODMSaveAs also has a callback, which uses = a=20 format string. The ODM_CONTENTFORMAT attribute can be requested = or set=20 using the ODMGetDocInfo and ODMSetDocInfo functions.

The ODMA 1.0 specification did not attempt to standardize the = format names=20 used by DMS and application vendors. This was a significant limitation = in some=20 cases. The DMS would not know in advance what type of file was being = created=20 by the application. Also an application that saved an existing file = back to=20 the DMS using a different format would have no standard format name to = give to=20 the DMS. This model relied on both the DMS and the application being = able to=20 auto-detect all file formats.

ODMA 2.0 defines guidelines to standardize format names. This has = become=20 necessary due to vendors=92 desire to have applications and DMSs more = tightly=20 integrated and because ODMA 2.0 introduces some new functions which = require=20 standardization in order to work. The new = ODMGetAlternateContent and=20 ODMSetAlternateContent functions require the DMS and = application to=20 have a standard way to identify file content. A new document attribute = called=20 ODM_ALTERNATE_RENDERINGS allows an application to find out if a = DMS can=20 provide a document in other formats and make a choice of which to = use.

ODMA has defined the following guidelines to standardize how a DMS = or=20 application might specify a document=92s content format:

  1. MIME Content Type. If a file type does not have a MIME content = type,=20 then a file extension must be used.=20
  2. File Extension (a.k.a. File Type). If a file extension is used = the first=20 character must be a dot. The file extension should be the one = normally used=20 to identify the document on the platform where the client = application is=20 running. Some platforms allow the file extension to contain more = than three=20 characters. ODMA does not define a maximum file extension length.=20
  3. File Extension plus other identifying information. This other=20 information may be useful in cases where a single file extension is = used for=20 different variations or versions of the file type. In this format = the first=20 character must be a dot, followed by the file extension, plus a = single=20 forward slash, plus a string containing the additional information. =

Examples:
application/msword=20

  • .doc=20
  • .doc/MS Word 95 Document=20
  • .doc/MS Word 97 Document

image/tiff=20

  • .TIF=20
  • .TIFF=20
  • .TIF/Tagged Image File Format=20
  • .TIF/Scanned TIFF

A DMS or application can use the Windows Registry or its own = mapping=20 capability to convert a file extension to a MIME code or vice versa. = Note that=20 some file extensions are used by more than one application, some file = types=20 have multiple valid file extensions, and that some MIME content types = are used=20 to define more than one file type within the same application. A DMS = or=20 application may have use whatever format name is most precise.

DMS or Native File System Dialogs = - Which=20 to Display First
ODMA imposes no rules on applications = requiring=20 them to always show the DMS dialogs first in response to filing = commands such=20 as File Open and File Save As. ODMA applications are encouraged to = provide a=20 user preference setting so the user can designate if the = application=92s native=20 file system dialog or the DMS=92s dialog is displayed first. Ideally = the=20 application may provide a push-button or some other control in its = native file=20 system dialog box to allow the user to quickly select the DMS dialog = box.=20

If the application cannot provide one or more of the options = described=20 above then they have no choice but to always display the DMS dialog = box in=20 response to the File Open and File Save As commands. Each ODMA = compliant DMS=20 must provide a way for the user to select the native file system from = dialogs=20 displayed while processing the ODMSelectDoc, = ODMSelectDocEx,=20 ODMNewDoc, ODMSaveAs and ODMSaveAsEx functions. = The DMS=20 returns the ODM_E_APPSELECT status if the user elects to use = the native=20 file system. When this status is returned the application can display = their=20 dialog box. If the user wishes to return to the DMS dialog box they = will have=20 to cancel and re-do the file command.

Character Sets
All strings = passed to or=20 returned from ODMA functions should be null-terminated series of = octets, in=20 the standard character set of the system on where ODMA is being used. = So for=20 example, 8859-1 would be used on English Windows, Shift-JIS would be = used on=20 Japanese Windows, etc. The term "null-terminated" as used in this=20 specification means terminated by the character set's natural Null = character.=20 For most character sets this means a single byte with the value 0x0.=20

If an application obtains an ODMA document ID on one platform and = later=20 uses it on another platform, the application is responsible for = translating=20 the ID to the character set being used on the second platform before = using it=20 there.

Application = Interfaces
An=20 ODMA-aware application can choose to communicate with the ODMA = Connection=20 Manager either through a traditional, function-oriented API or through = Component Object Model (COM) interfaces. Prototypes and constants used = for the=20 function-oriented API are included in the odma.h header file. = Prototypes,=20 constants, and interface definitions for the COM interface are = included in the=20 odmacom.h header file.=20

After calling ODMRegisterApp, applications can obtain one or = more=20 COM interfaces to ODMA through the ODMQueryInterface function. = The=20 IODMDocMan interface provides an alternate entry point to most = of the=20 ODMA functions documented below. Other functions are defined in the=20 IODMDocMan2 and IODMQuery interfaces. These interfaces = and their=20 interface IDs are defined in the odmacom.h header file.=20

Note that IODMDocMan::QueryInterface will only query the = default DMS=20 for the calling application. The application must call = ODMQueryInterface in=20 order to query other DMSs.

Query Syntax
The query syntax = described=20 here is used in the ODMQueryExecute function.=20

<query> :: select <returned_list> = <search_criteria>
<returned_list> :: <returned_item> [, <returned_list>]
<returned_item> :: ODM_DOCID
:: ODM_NAME
<search_criteria> :: <search_clause>
:: <where_clause>
::=20 <search_clause> <where_clause>
:: = <where_clause>=20 <search_clause>
<search_clause> :: search document contains <expression>
<expressioin> :: (<expression>)
:: [not] (<expression>)
:: = <term> [<operator> <expression>]
<term> :: =91<word>=92
:: [not] = =91<word>=92
<operator> :: and
:: or
<word> is a user supplied word. If there is a single quote (=92) = inside this=20 word, it needs to be represented with two consecutive single = quotes=20 (=92=92).
<where_clause> :: where <condition_list>
<condition_list> :: <condition> [<operator> = <condition_list>]
<condition> :: <attribute> <op>
=91<attribute_value>=92<attribute> :: ODM_FORMAT
:: ODM_NAME
:: ODM_AUTHOR
:: = ODM_TYPE
::=20 ODM_DMS_DEFINED:<dms_attribute>
:: * Any other = document=20 attribute listed in Appendix A
<op> :: =3D
:: !=3D
:: <>
:: >
:: <
:: = <=3D
::=20 >=3D
<dms_attribute> is a DMS specific attribute name.
<attribute_value> is a user supplied value for ODM_NAME, etc. If there is a = single=20 quote (=92) inside any of these names, it must be represented = with two=20 consecutive single quotes (=92=92).

Query Examples
Example 1: select ODM_DOCID, ODM_NAME
where ODM_TYPE =3D = =91Memo=92
search=20 document contains =91Internet=92 and not = =91Intranet=92
Example 2: select ODM_DOCID, ODM_NAME
where ODM_AUTHOR =3D =91Mark = Twain=92 and=20 ODM_TYPE =3D =91Story=92
Example 3: select ODM_DOCID, ODM_NAME
search document contains = =91Mary=92=92s=20 Lamb=92
where ODM_NAME =3D =91Mary Has a Little Lamb=92 and=20 ODM_TYPE =3D =91Song=92
Example 4: select ODM_DOCID, ODM_NAME
search document contains = (=91rabbit=92 or=20 =91hare=92) and not =91bunny=92
where ODM_NAME =3D =91Wild = Life=92 and=20 ODM_AUTHOR =3D =91John Doe=92 and ODM_TYPE =3D=20 =91Letter=92

ODMA API
The following = section=20 describes each function in the ODMA API that a typical application = would use.=20 The functions are listed in alphabetical order.

ODMActivate

ODMSTATUS ODMActivate (ODMHANDLE handle, WORD action, LPSTR = lpszDocId)=20

This function causes the DMS to perform actions that do not require = cooperation from the calling application. Control is returned to the = calling=20 application after the specified action has been completed, except = where noted.=20 A DMS is not required to support all of these actions.=20

Parameters:
handle - in - A handle obtained by a = previous=20 ODMRegisterApp call.=20

action - in - One of the following action codes:=20

ODM_NONE - No specific action is requested. The DMS should = simply=20 make itself visible and let the user select the action to be = performed.=20

ODM_DELETE - The DMS should delete the specified document. = Note that=20 most DMSs will not allow a deletion to occur if the document is = currently in=20 use.=20

ODM_SHOWATTRIBUTES - The DMS should display the specified = document's=20 profile or attributes.=20

ODM_EDITATTRIBUTES - The DMS should display the specified = document's=20 profile or attributes, and the user should be put in edit mode. Note = that some=20 DMSs will not allow a document's attributes to be edited while it is = in use.=20

ODM_VIEWDOC - The DMS should display the specified document = in a=20 viewer window. The DMS may return control to the calling application = before=20 displaying the document.=20

ODM_OPENDOC - The DMS should open the specified document in = its=20 native application. The DMS may return control to the calling = application=20 before displaying the document. This function is intended for use by=20 applications other than the document's native application (e-mail, = workflow,=20 annotation, etc.). Applications should use ODMOpenDoc to access their = own=20 documents. If this function fails, the calling application may wish to = retry=20 using the ODM_VIEWDOC action code.=20

ODM_NEWDOC - The DMS should allow the user to create and = save a new=20 document. Optionally the caller can specify a template document in = lpszDocId .=20 If lpszDocId is Null the DMS should allow the user to choose the file = format=20 of the document to be created and the document template. In most cases = it is=20 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=20 calling application will not get notification when the new document = has been=20 created. The user is free to cancel this function.=20

ODM_CHECKOUT - The DMS should check-out/reserve the document = for the=20 current user. The DMS can display whatever UI it might use for = document=20 check-out. This action allows the user to explicitly reserve a = document in the=20 DMS in a way that is persistent across ODMA or DMS sessions. = ODMOpenDoc should=20 be used to get the content file. See ODMCloseDoc and ODMCloseDocEx for = recommendations on how to handle closing a document that was = explicitly=20 reserved before it was opened.=20

ODM_CANCELCHECKOUT - The DMS should cancel a previous=20 checkout/reserve on the document, if it has been checked-out by the = current=20 user. The DMS can display whatever UI it might use for canceling a = document=20 check-out.=20

ODM_CHECKIN - The DMS should check-in/unreserve the document = if it=92s=20 checked-out by the current user. The DMS can display whatever UI it = might use=20 for document check-in. ODMSaveDoc or ODMSaveDocEx should already have = been=20 used, if necessary, to save the content to the DMS.=20

ODM_SHOWHISTORY - The DMS should display the specified = document=92s=20 history (i.e. revisions, events, activities, etc.).=20

lpszDocId - in - A document ID specifying the document on which to = perform=20 the requested action. This parameter may be Null if the action is=20 ODM_NONE or ODM_NEWDOC. If action is ODM_NEWDOC = the=20 application can specify the document ID of a template document.=20

Return value:

ODM_SUCCESS if successful.
ODM_E_DOCID if the = document ID=20 is invalid or refers to a document that no longer=20 exists.
ODM_E_INUSE if the document is currently in use or=20 checked-out by another user on actions where this would preclude the = operation=20 from completing correctly. ODM_E_ACCESS if the user doesn=92t = have=20 appropriate access rights to perform the requested action (i.e. = check-out or=20 check-in the document).
ODM_E_OFFLINE if the DMS cannot = currently=20 access the document because the user client is=20 off-line.
ODM_E_ARCHIVED if the DMS cannot currently supply = the=20 document content because it has been archived.
ODM_E_CANCEL = if the=20 action was canceled by the user.
ODM_E_NOSUPPORT if action = is not=20 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=20 completed by the DMS.
ODM_W_NOACTION if action is = ODM_CHECKOUT and=20 the document is already checked-out/reserved by the current user. This = status=20 can also be returned if action is either ODM_CANCELCHECKOUT or=20 ODM_CHECKIN and the document is not currently = checked-out/reserved by=20 any user.
ODM_E_HANDLE if handle was invalid.

ODMCloseDoc
ODMSTATUS=20 ODMCloseDoc( ODMHANDLE handle, LPSTR lpszDocId, DWORD activeTime, = DWORD=20 pagesPrinted, LPVOID sessionData, WORD dataLen)=20

An application that has opened a document by calling ODMOpenDoc = must call=20 ODMCloseDoc when it is finished using the document. The = application=20 should not call this function until after it has closed the document, = because=20 the DMS may move the document or make it inaccessible as a result of = this=20 call. Note that this function will not cause the document to be saved = into the=20 DMS's persistent repository unless ODMSaveDoc has been called=20 previously.=20

It is possible for a user to explicitly check-out/reserve a = document using=20 either ODMActivate or a command provided by the DMS. If a = document was=20 already reserved by the user before ODMOpenDoc was called, then = when=20 ODMCloseDoc is called it is recommended that the DMS keep the = document=20 reserved. The DMS should only check-in/unreserve the document in=20 ODMCloseDoc if it first displays a dialog box confirming this = with the=20 user.=20

Parameters:
handle - in - A handle obtained by a previous = ODMRegisterApp call.
lpszDocId - in - A null-terminated = document ID.=20 This is typically obtained by a call to ODMSelectDoc or=20 ODMNewDoc. This document must have been previously opened by a = call to=20 ODMOpenDoc.
activeTime - in - If the application tracks time spent = editing=20 the document then it should pass the number of seconds here. Otherwise = it=20 should pass 0xFFFFFFFF.
pagesPrinted - in - If the application = tracks the=20 number of pages printed from this document during the current editing = session;=20 it should pass this number here. Otherwise it should pass=20 0xFFFFFFFF.
sessionData - in - The application may pass other = information=20 regarding the current editing session in this parameter. For example, = an=20 application might pass the number of keystrokes that were entered. The = calling=20 application is free to determine the format of this data, so DMSs that = rely on=20 this information will have to coordinate with each application = supported. Null=20 should be passed if the application has no meaningful information to = pass=20 through this parameter.
dataLen - in - The length of the data = passed in the=20 sessionData parameter. Ignored if sessionData is Null.

Return value:
ODM_SUCCESS if=20 successful.
ODM_E_NOOPEN if the document was not previously=20 opened.
ODM_E_FILELOCKED if the DMS could not complete the = function=20 because the temporary file provided in ODMOpenDoc is still = opened by=20 the calling application.
ODM_E_FAIL if the DMS is unable to = close=20 the document for any other reason.
ODM_E_HANDLE if handle = was=20 invalid.

ODMCloseDocEx

ODMSTATUS ODMCloseDocEx( ODMHANDLE handle, LPSTR lpszDocId, LPDWORD = pdwFlags, DWORD activeTime, DWORD pagesPrinted, LPVOID sessionData, = WORD=20 dataLen)=20

ODMCloseDocEx is the same as ODMCloseDoc except it = has a=20 pwdFlags parameter. There is an ODM_SILENT flag to facilitate=20 unattended document processing. Some DMSs display a user interface = when=20 closing a document. This flag allows the calling application to = suppress this=20 UI.=20

An application that has opened a document by calling = ODMOpenDoc must=20 call ODMCloseDoc or ODMCloseDocEx when it is finished = using the=20 document. The application should not call this function until after it = has=20 closed the document, because the DMS may move the document or make it=20 inaccessible as a result of this call. Note that this function will = not cause=20 the document to be saved into the DMS's persistent repository unless=20 ODMSaveDoc or ODMSaveDocEx has been called previously.=20

It is possible for a user to explicitly check-out/reserve a = document using=20 either ODMActivate or a command provided by the DMS. If a = document was=20 already reserved by the user before ODMOpenDoc was called, then = when=20 ODMCloseDocEx is called it is recommended that the DMS keep the = document reserved. The DMS should only check-in/unreserve the document = in=20 ODMCloseDocEx if the ODM_SILENT flag is not set and it = first=20 displays a dialog box confirming this with the user.

Parameters:
handle - in - A handle obtained by a previous = ODMRegisterApp call.
lpszDocId - in - A null-terminated = document ID.=20 This is typically obtained by a call to ODMSelectDoc,=20 ODMSelectDocEx or ODMNewDoc. This document must have = been=20 previously opened by a call to ODMOpenDoc.
pdwFlags - in/out - A = pointer to=20 a variable containing flags used on both input and output. On input, 0 = or the=20 following flag:=20

ODM_SILENT - The DMS should not require user interaction = while=20 satisfying the call. If the call cannot be satisfied without user = interaction=20 then an error should be returned.
ODMA 2.0 does not define any = output flags=20 at this time.

activeTime - in - If the application tracks time spent editing the = document=20 then it should pass the number of seconds here. Otherwise it should = pass=20 0xFFFFFFFF.
pagesPrinted - in - If the application tracks the = number of=20 pages printed from this document during the current editing session; = it should=20 pass this number here. Otherwise it should pass = 0xFFFFFFFF.
sessionData -=20 in - The application may pass other information regarding the current = editing=20 session in this parameter. For example, an application might pass the = number=20 of keystrokes that were entered. The calling application is free to = determine=20 the format of this data, so DMSs that rely on this information will = have to=20 coordinate with each application supported. Null should be passed if = the=20 application has no meaningful information to pass through this=20 parameter.
dataLen - in - The length of the data passed in the = sessionData=20 parameter. Ignored if sessionData is Null.

Return value:

ODM_SUCCESS if successful.
ODM_E_NOOPEN if the = document=20 was not previously opened.
ODM_E_USERINT if the = ODM_SILENT=20 flag was specified and the DMS could not satisfy the call without user = interaction.
ODM_E_FILELOCKED if the DMS could not complete = the=20 function because the temporary file provided in ODMOpenDoc is = still=20 opened by the calling application.
ODM_E_FAIL if the DMS is = unable=20 to close the document for any other reason.
ODM_E_HANDLE if = handle=20 was invalid.

ODMGetAlternateContent

ODMSTATUS ODMGetAlternateContent(ODMHANDLE handle, LPSTR lpszDocId, = LPDWORD=20 pdwFlags, LPSTR lpszFormat, LPSTR lpszDocLocation)=20

This function causes the DMS to return an alternate content file = for the=20 specified document. The format of the alternate content file should be = one of=20 the formats returned by the ODM_ALTERNATE_RENDERINGS item in a = previous=20 call to ODMGetDocInfo. The application is responsible for = deleting the=20 alternate content file when it is finished using it.

Parameters:

handle - in - A handle obtained by a previous ODMRegisterApp=20 call.
lpszDocId - in - A null-terminated document ID. This is = typically=20 obtained by a call to ODMSelectDoc, ODMSelectDocEx or=20 ODMNewDoc. The specified document may or may not be open when = this=20 function is called. This document ID refers to the main document for = which an=20 alternate content file is being requested.=20

pdwFlags - in/out - A pointer to a variable containing flags used = on both=20 input and output. On input, zero (0) or the following flag:=20

ODM_SILENT - The DMS should not require user interaction = while=20 satisfying the call. If the call cannot be satisfied without user = interaction=20 then an error should be returned.=20

ODMA 2.0 does not define any output flags at this time.=20

lpszFormat - in - A null-terminated string containing the format = name of=20 the alternate format requested. The Document Format Names section has=20 information on how file formats are identified in ODMA. Typically the = calling=20 application would have first obtained the alternate renderings the DMS = has for=20 the specified document then specified one in this parameter. This is = done by=20 requesting the ODM_ALTERNATE_RENDERINGS attribute in=20 ODMGetDocInfo. However, the application is free to simply = specify the=20 MIME Content Type or File Extension for the format it needs. If the = DMS cannot=20 return the requested format, it will return the ODM_E_NOSUPPORT = status.=20

lpszDocLocation - in/out - A pointer to a buffer of at least=20 ODM_FILENAME_MAX bytes in length, into which the DMS will write = a=20 null-terminated string containing a full path and file name of the = alternate=20 content file. If an error occurs then the contents of the buffer will = be=20 undefined. It is the responsibility of the calling application, not = the DMS,=20 to delete this file when it is finished with it.=20

Optionally the calling application can specify a file extension in = this=20 parameter for the DMS to use in the file specification it returns. If=20 specified, the file extension should be preceded by a period. The DMS = may=20 choose to ignore this information and return a file specification = containing a=20 different file extension.=20

Return value:

ODM_SUCCESS if successful.
ODM_E_ACCESS if the = user does=20 not have access rights to the requested alternate content file or the = main=20 document.
ODM_E_INUSE if the user is currently unable to = access the=20 alternate content file because the main document is checked-out by = another=20 user.
ODM_E_DOCID if the document ID is invalid or refers to = a=20 document that no longer exists.
ODM_E_OFFLINE if the DMS = cannot=20 currently access the document because the user client is=20 off-line.
ODM_E_ARCHIVED if the DMS cannot currently supply = the=20 document content because it has been archived.
ODM_E_USERINT = if the=20 ODM_SILENT flag was specified and the DMS could not make the specified = document available without user interaction.
ODM_E_INVARG if = the=20 value in flags is invalid.
ODM_E_REQARG if a required = parameter=20 isn=92t specified (i.e. lpszFormat or lpszDocLocation=20 ).
ODM_E_NOSUPPORT if the DMS does not support the function = or it=20 cannot return the requested alternate content format for the specified = document.
ODM_E_FAIL if the DMS is unable to make the = document=20 accessible for any other reason.
ODM_E_HANDLE if handle was=20 invalid.

ODMGetDMS

WORD ODMGetDMS( LPCSTR lpszAppId, LPSTR lpszDmsId )=20

This function provides an application a programmatic way to get its = default=20 DMS. The DMS ID of the current DMS for the application will be = returned. This=20 can be either the default DMS from the registry or a DMS previously = set by the=20 application using ODMSetDMS.=20

Parameters:

lpszAppId - in - A pointer to a null-terminated string containing = an=20 Application ID.=20

lpszDmsId - out - A pointer to a buffer to receive the DMS ID of = the=20 default DMS. This buffer must be at least ODM_DMSID_MAX bytes = in=20 length. If an error occurs the value in this buffer is undefined.=20

Returns value:

ODM_SUCCESS if successful.
ODM_E_NODMS if there is = no=20 default DMS registered.

ODM_E_REQARG if either parameter is not = specified.

ODMGetDMSCount

WORD ODMGetDMSCount( )=20

This is an informational function. It will count the number of DMSs = currently registered on the system. This information can be used to = determine=20 the minimum size for the buffer in a call to ODMGetDMSList.=20

Parameters: None.=20

Return value: The number of DMSs currently registered on the = system.=20

ODMGetDMSInfo

ODMSTATUS ODMGetDMSInfo( ODMHANDLE handle, LPSTR lpszDmsId, LPWORD = pwVerNo,=20 LPDWORD pdwExtensions )=20

This function returns information to the application about the = currently=20 active DMS. The application if free to only request the information it = needs.=20

Parameters:

handle - in - A handle obtained by a previous ODMRegisterApp = call.

lpszDmsId - out - If specified by the caller, this should be a = pointer to a=20 buffer of at least ODM_DMSID_MAX bytes in length. A = null-terminated ID=20 identifying the DMS is returned here. This is the same ID embedded in = document=20 IDs returned by this DMS.
pwVerNo - out - If specified by the = caller, this=20 should be a pointer to a variable to receive a version number. The = version of=20 the ODMA API supported by this DMS is returned here.

pdwExtensions - out - If specified by the caller, this should be a = pointer=20 to a variable to receive extension information. Indications of = extensions to=20 the base ODMA API that are supported by this DMS are returned here. If = a DMS=20 does not support any currently defined extensions, then 0 will be = returned.=20 The DMS will return flag values for all the extensions it supports. = The=20 currently defined ODMA extensions are:=20

ODM_EXT_WORKFLOW - The DMS supports the ODMA Workflow=20 Extensions.
ODM_EXT_QUERY - The DMS supports the Query = Extensions=20 defined in ODMA 1.5.

Return value:

ODM_SUCCESS if successful.
ODM_E_HANDLE if handle = was=20 invalid.

ODMGetDMSList

WORD ODMGetDMSList( LPSTR buffer, WORD buffer_size )=20

This function gets a list of the DMSs currently registered on the = system.=20

Parameters:=20

buffer - out - A pointer to a buffer which will receive a list of = DMSs. The=20 format of the list is a collection of Null terminated strings. The = list is=20 terminated by an empty string (i.e. "<id#1>\0<id#2>\0\0"). =

buffer_size - in - Size of buffer . It must be at least = ODMGetDMSCount()=20 * ODM_DMSID_MAX + 1 bytes in length.=20

Return value: The number of DMSs returned in buffer.

ODMGetDocInfo

ODMSTATUS ODMGetDocInfo( ODMHANDLE handle, LPSTR lpszDocId, WORD = item,=20 LPSTR lpszData, WORD dataLen )=20

An application can use this function to obtain information about a = document=20 from the DMS. It is recommended that the DMS not display any user = interface=20 while processing this function.=20

Parameters:=20

handle - in - A handle obtained by a previous ODMRegisterApp call.=20

lpszDocId - in - A null-terminated document ID. This is typically = obtained=20 by a call to ODMSelectDoc , ODMSelectDocEx or ODMNewDoc . The = specified=20 document may or may not be open when ODMGetDocInfo is called.=20

item - in - A single Item Id.=20

Refer to Appendix A for a complete list of Item Ids for document = attributes=20 which can be specified in this parameter.=20

ODM_DMS_DEFINED - Can be used for DMS specific attributes not = explicitly=20 defined by ODMA. The lpszData parameter contains a DMS-specific = indication of=20 the data to be returned. Note that an application must know which DMS = it is=20 talking to and must understand the data indications supported by the = DMS in=20 order to use this item id.=20

lpszData - in/out - On input, ignored if item is anything other = than=20 ODM_DMS_DEFINED . If item is ODM_DMS_DEFINED then lpszData contains an = indication of the data to be returned. It is recommended that the DMS = be able=20 to recognize a null-terminated string containing one of its known = attribute=20 names. On output, the requested data is returned in the buffer pointed = to by=20 lpszData . The data is always null-terminated.=20

dataLen - in - The length of the output buffer pointed to by = lpszData . If=20 the data to be returned is longer than dataLen it will be truncated. = The DMS=20 must return ODM_E_TRUNCATED when the requested data cannot be safely=20 truncated; for example when an attribute containing a document ID or = URL is=20 returned. In these cases the application should recall the function = supplying=20 a larger buffer.=20

Return value:

ODM_SUCCESS if successful.
ODM_E_DOCID if the document ID is = invalid or=20 refers to a document that no longer exists.
ODM_E_OFFLINE if the = DMS cannot=20 currently access the document because the user client is=20 off-line.
ODM_E_TRUNCATED if the application supplied buffer is too = small=20 to hold data that cannot be safely truncated. A DMS cannot truncate an = ODM_URL=20 attribute or any attribute containing an ODMA document = ID.
ODM_E_ITEM if=20 item is invalid or unknown to this DMS.
ODM_E_NOSUPPORT if the DMS = does not=20 support the function or does not support the specified document=20 attribute.
ODM_E_HANDLE if handle was invalid.

ODMGetDocRelation

ODMSTATUS ODMGetDocRelation( ODMHANDLE handle, LPSTR lpszDocId, = LPDWORD=20 pdwFlags, LPSTR lpszLinkedId, LPSTR lpszFormat, LPSTR lpszPreviousId ) =

An application can use this function to retrieve pointers to = document=20 versions linked to a particular document ID. This function would be = used=20 typically as part of retrieving a compound document. It could also be = used=20 when saving an updated component document, for the user to verify = which=20 compound documents will be impacted by any changes.=20

Parameters:=20

handle - in - A handle obtained by a previous ODMRegisterApp = call.

lpszDocId - in - A null-terminated document ID. This is typically = obtained=20 by a call to ODMSelectDoc or ODMNewDoc . The specified document may or = may not=20 be open when ODMGetDocRelation is called.=20

pdwFlags - in/out - A pointer to a variable containing flags used = on both=20 input and output. On input, one or more of the following flags:=20

ODM_REL_PARENT - Return the lpszLinkedId that is a parent of = lpszDocId .=20

ODM_REL_CHILD - Return the lpszLinkedId that is a child of = lpszDocId=20 .=20

ODM_SILENT - The DMS should not require user interaction = while=20 satisfying the call. If the call cannot be satisfied without user = interaction=20 then an error should be returned.=20

Upon return one or more of the following flags may be set by the = DMS unless=20 an error occurred:=20

ODM_REL_NOTORDERED - The default is that the DMS maintains = child=20 links as an ordered list, and that it will use lpszPreviousId to = select the=20 appropriate lpszLinkedId to return. If it is returning them in no = particular,=20 logical, meaningful sequence, the DMS will return this value to warn = the=20 application. A DMS could maintain both ordered and unordered lists, an = example=20 of the former being a book with separate chapters, while the latter = might be a=20 collection such as attached to a workflow.=20

ODM_REL_FIXED - The relationship is frozen between the = particular=20 document versions represented by lpszDocId and lpszLinkedId . This may = also be=20 used to signify that the application and/or the user want to retain = control=20 over updating the link, rather than have the DMS do it.=20

ODM_REL_RELEASED - The link should be maintained to the = Current or=20 Released version of the child document. Released is available in some = DMS to=20 distinguish a version that has been approved for release. If the DMS = does not=20 distinguish between Released and Latest, then Latest is used. The = value is=20 called Released and not Current, to avoid confusion with the version = that is=20 already (currently) linked.=20

ODM_REL_LATEST - The link should be maintained to the latest = version=20 of the child document.=20

lpszLinkedId - out - A pointer to a buffer where the DMS will = return the ID=20 of the next document version that is linked to lpszDocId . This buffer = must be=20 at least ODM_DOCID_MAX bytes in length. If successful then a=20 null-terminated document ID will be returned here. Otherwise the = contents of=20 the buffer will be undefined.=20

lpszFormat - in/out - This is an optional parameter. If specified = it must=20 be a pointer to a buffer of at least ODM_FORMAT_MAX characters. = This=20 buffer contains a null-terminated string naming the file format of the = rendition to be retrieved when the link is followed. Refer to the = Document=20 Format Names section for information on how file formats are = identified in=20 ODMA. This parameter allows the caller to identify the best format for = the=20 intended use of the main document. The requested format may or may not = be the=20 one established in ODMSetDocRelation and may or may not be the = primary=20 editing format. For instance, a graphic may be saved in several = resolutions,=20 one for on-line use and another for printing.=20

On input, this is a hint to the DMS of the preferred format of the = child to=20 be retrieved. If the application does not provide a format it should = set the=20 buffer in lpszFormat to a zero length string. In this case the DMS = should use=20 the format established in ODMSetDocRelation or the primary = format of=20 the document.=20

On output, the DMS should write the format name of the rendition = returned.=20 This may be the closest rendition format the DMS could find. If the = DMS does=20 not record rendition formats when relating documents, then it should = return a=20 zero length string in this buffer.=20

If this parameter is Null, then the DMS should use the format = established=20 in ODMSetDocRelation or the primary format of the child = document (the=20 one used in ODMOpenDoc ).=20

lpszPreviousId - in - A null-terminated document ID. This is = typically=20 returned as lpszLinkedId on a previous call to = ODMGetDocRelation. By=20 making repeated calls to ODMGetDocRelation , the application = obtains a=20 logically ordered list of document ID's that make up a compound = document. To=20 get the first document in a list, provide a zero length, = null-terminated=20 document ID. Null should be passed if the application has no = meaningful=20 information to pass through this parameter.=20

Return value:=20

ODM_SUCCESS if successful.
ODM_E_NORELATION if the = specified document has no related parent or = child.
ODM_E_NOMOREDATA=20 if the end of the list has been passed.
ODM_E_DOCID if a = document ID=20 is invalid or refers to a document that no longer=20 exists.
ODM_E_USERINT if the ODM_SILENT flag was specified = and the=20 DMS could not satisfy the call without user=20 interaction.
ODM_E_NOSUPPORT if the DMS does not support the = function.
ODM_E_INVARG if the value specified in pdwFlags = was=20 invalid.
On input either ODM_REL_PARENT or ODM_REL_CHILD must be = set.=20 ODM_E_REQARG if a required parameter (i.e. lpszLinkedId ) is=20 Null.
ODM_E_HANDLE if handle was = invalid.
ODM_E_FAILif the=20 specified data was invalid or the DMS was unable to accept it for = other=20 reasons.

ODMGetLeadMoniker

ODMSTATUS ODMGetLeadMoniker( ODMHANDLE handle, LPSTR lpszDocId, = LPMONIKER=20 FAR *ppMoniker )=20

Applications that are OLE 2 servers typically form composite = monikers for=20 their OLE links by combining a file moniker representing the document = with one=20 or more item monikers representing a particular section of the = document. This=20 approach often does not work in environments where Document Management = Systems=20 are in use because the filename that the application sees is usually = just=20 temporary. This function lets the application obtain a leading moniker = from=20 the DMS that can be used in place of the file moniker.=20

This function will only be available on platforms supporting OLE 2. = This=20 function may not be supported by some DMSs; those DMSs will return=20 ODM_E_FAIL . In this case the application should go ahead and = use the=20 file moniker as though ODMA were not present. Note that this function = is=20 prototyped in odmacom.h instead of odma.h, so that non-OLE-aware = applications=20 do not have to #include the OLE header files.=20

Parameters:

handle - in - A handle obtained by a previous ODMRegisterApp = call.=20

lpszDocId - in - An ODMA document ID.=20

ppMoniker - out - A leading moniker for the specified document ID = will be=20 returned here if successful. Otherwise Null will be returned here.=20

Return value:=20

ODM_SUCCESS if successful.
ODM_E_FAIL if the DMS = that=20 created the specified document ID does not support OLE moniker=20 building.
ODM_E_DOCID if the document ID is invalid or = refers to a=20 document that no longer exists.
ODM_E_HANDLE if handle is=20 invalid.

ODMNewDoc

ODMSTATUS ODMNewDoc( ODMHANDLE handle, LPSTR lpszDocId, DWORD = dwFlags,=20 LPSTR lpszFormat, LPSTR lpszDocLocation )=20

This function causes the DMS to create a new document profile and = return=20 the document ID for the new document to the calling application. The = DMS may=20 create a temporary or pending document profile; it may not have = actually=20 created a document in its data store. If the DMS displays a dialog box = for=20 this function it should be task/application modal.=20

The document ID returned by the DMS in ODMNewDoc provides a = document=20 context for the application. This document ID must be used in = subsequent ODMA=20 function calls which are needed to complete the process of saving a = new=20 document into a DMS. If the user decides to cancel the operation or = save the=20 document to the native file system, then the application should call=20 ODMCloseDoc or ODMCloseDocEx and throw the document ID = away. The=20 document ID returned by ODMNewDoc may be temporary so the application = must be=20 prepared for the possibility that the DMS will later override it in a = call to=20 ODMSaveAs , ODMSaveAsEx or ODMSaveDoc or = ODMSaveDocEx=20 .=20

The calling sequence for creating a new document, which isn=92t = based on=20 another existing document, is as follows: ODMNewDoc , = ODMSaveAs=20 , ODMOpenDoc then ODMSaveDoc . Finally the document must = be=20 closed with ODMCloseDoc . The above sequence will likely involve user=20 interaction with the DMS displaying one or more dialog boxes.=20

It is possible for an application to create a new document without = any user=20 interaction if the DMS supports it. To accomplish this the calling = application=20 should set the ODM_SILENT flag and use the following call = sequence:=20 ODMNewDoc , {ODMSetDocInfo}, ODMSaveAsEx ,=20 ODMOpenDoc , ODMSaveDocEx and ODMCloseDocEx.=20

Optionally, if the application wishes to pre-set some document = attributes=20 in the Save As dialog box it can call ODMSetDocInfo using the = document=20 ID from ODMNewDoc . This should be done before calling = ODMSaveAs=20 or ODMSaveAsEx . Example attributes the DMS might accept and = perhaps=20 show in its Save As dialog are ODM_NAME , ODM_AUTHOR ,=20 ODM_KEYWORDS and others. After ODMSaveAs is called, the=20 application might wish to call ODMGetDocInfo to see if the user = changed=20 the value of any document attribute it is tracking.=20

Parameters:=20

handle - in - A handle obtained by a previous ODMRegisterApp = call.=20

lpszDocId - out - A pointer to a buffer where the DMS will return = the ID of=20 the new document. This buffer must be at least ODM_DOCID_MAX bytes in = length.=20 If successful then a null-terminated document ID will be returned = here.=20 Otherwise the contents of the buffer will be undefined.=20

dwFlags - in - 0 or a combination of 1 or more of the following = values:=20

ODM_SILENT - The DMS should not require user interaction = while=20 satisfying the call. If the call cannot be satisfied without user = interaction=20 then an error should be returned.=20

lpszFormat - in - A null-terminated string naming the format of the = new=20 document's content. Refer to the Document Format Names section for = information=20 on how file formats are identified in ODMA. Note that this may be = changed=20 later via an ODMSaveAs call.=20

lpszDocLocation - in - Normally DMSs select the location for a new=20 document. But if the document already exists and is large or resides = on=20 read-only storage then the calling application can use this parameter = to tell=20 the DMS where the document is currently stored. This is a hint to the = DMS that=20 the document should be left in this location. Note that some DMSs may = ignore=20 this hint and move the document anyway. A DMS may ignore this = parameter. The=20 calling application should not directly access the document in this = location=20 following the call to ODMNewDoc ; it should use = ODMOpenDoc to=20 obtain a location for subsequent access to the document. In most cases = the=20 application should pass Null in this parameter to allow the DMS to = determine=20 the document's storage location.=20

Return value:=20

ODM_SUCCESS if successful.
ODM_E_CANCEL if the = user=20 cancels the new document creation.
ODM_E_FAIL if the DMS = failed to=20 create the new document.
ODM_E_USERINT if the = ODM_SILENT flag=20 was specified and the DMS could not process the function without user=20 interaction.
ODM_E_APPSELECT if the user indicated that he = wants to=20 select the document's filename using the application's regular file = selection=20 facilities rather than using the DMS. The application should just = display its=20 regular selection dialog.
ODM_E_OFFLINE if the DMS has no = local data=20 store and is off-line from its server; generally the caller should = treat this=20 the same as ODM_E_APPSELECT.
ODM_E_HANDLE if handle = was=20 invalid.

ODMOpenDoc

ODMSTATUS ODMOpenDoc( ODMHANDLE handle, DWORD flags, LPSTR = lpszDocId, LPSTR=20 lpszDocLocation )=20

This function causes the DMS to make a document available to the=20 application. It performs any necessary pre-processing (mapping network = drives,=20 checking security, etc.) and then returns to the application a = temporary=20 filename that can be used to access the document during the current = session.=20 Note that this function does not open the document file; it merely = makes the=20 file temporarily available to the calling application. The application = can=20 then open, read, write and close the file as needed.=20

If ODM_MODIFYMODE is requested, the DMS may refuse the = request if=20 the user has view-only rights ( ODM_E_ACCESS ) or if the = document is=20 currently checked-out ( ODM_E_INUSE ) to another user. It is=20 recommended that the application retry the request specifying = ODM_VIEWMODE in=20 both cases so that the user can at least view the document and = possibly save=20 changes to a new document.=20

Applications are encouraged to give the user the same level of = feedback if=20 a DMS based document is opened for read-only access as they would for = a=20 document based in the platform=92s native file system.=20

When the application is finished using a file which was opened with = either=20 ODM_MODIFYMODE or ODM_VIEWMODE it must call = ODMCloseDoc=20 or ODMCloseDocEx . When an application is finished using a file = that=20 was obtained with the ODM_REFCOPY option it does not have to = call=20 ODMCloseDoc or ODMCloseDocEx , however, it must delete = the=20 temporary file.=20

If an application has opened a document in ODM_VIEWMODE and = wishes=20 to switch to ODM_MODIFYMODE, it must first call = ODMCloseDoc or=20 ODMCloseDocEx then call ODMOpenDoc requesting=20 ODM_MODIFYMODE. The same is true if the application wishes to = switch=20 from ODM_MODIFYMODE to ODM_VIEWMODE . The=20 ODM_E_ALREADYOPENED error status is returned by the DMS if the=20 application attempts to re-open a document that it has already opened = in=20 either of these two modes.=20

Parameters:

handle - in - A handle obtained by a previous ODMRegisterApp = call.=20

flags - in - One or more of the following flags:=20

ODM_MODIFYMODE - The DMS should make the document available = in a=20 modifiable mode. This mode is assumed if ODM_VIEWMODE or=20 ODM_REFCOPY is not explicitly requested.=20

ODM_VIEWMODE - The DMS should make the document available in = a=20 view-only mode. Any changes made to the document will not be = transferred back=20 to the document repository. If ODM_VIEWMODE and = ODM_MODIFYMODE=20 are both specified in the same call the ODM_E_INVARG error will = be=20 returned.=20

ODM_REFCOPY - The DMS should make a read-only reference copy = of the=20 document available to the calling application. The DMS must return a = different=20 filespec in lpszDocLocation each time this function is called. It is = invalid=20 to specify ODM_REFCOPY with either ODM_VIEWMODE or=20 ODM_MODIFYMODE . The calling application must delete any = reference copy=20 file obtained using this option and it should not call = ODMCloseDoc or=20 ODMCloseDocEx .=20

ODM_SILENT - The DMS should not require user interaction = while=20 satisfying the call. If the call cannot be satisfied without user = interaction=20 then an error should be returned.=20

lpszDocId - in - A document ID. This is typically obtained by a = call to=20 ODMSelectDoc or ODMNewDoc .=20

lpszDocLocation - out - A pointer to a buffer of at least=20 ODM_FILENAME_MAX bytes in length. The DMS will store in this = buffer a=20 null-terminated string indicating where the caller can access the = document=20 during the current session. Typically, this will be the full path/file = name of=20 the specified document, but some document formats may dictate another = type of=20 location such as a directory name. If an error occurs then the = contents of the=20 buffer will be undefined.=20

Return value:

ODM_SUCCESS if successful.
ODM_E_ACCESS if the = user does=20 not have the access rights requested (for example, modify mode was = requested=20 but the user only has view rights to the = document).
ODM_E_INUSE if=20 the user is currently unable to access the document in modify mode = because it=20 is checked-out by another user. This differs from ODM_E_ACCESS = in that=20 it is expected that the user might be able to access the document in = the=20 specified mode at some point in the future.
ODM_E_DOCID if = the=20 document ID is invalid or refers to a document that no longer=20 exists.
ODM_E_OFFLINE if the DMS cannot currently access the = document because the user client is off-line.
ODM_E_ARCHIVED = if the=20 DMS cannot currently supply the document content because it has been=20 archived.
ODM_E_USERINT if the ODM_SILENT flag was specified = and the=20 DMS could not make the specified document available without user=20 interaction.
ODM_E_INVARG if both ODM_OPENMODE and=20 ODM_VIEWMODE have been specified or if either of those modes = was=20 specified with ODM_REFCOPY .
ODM_E_ALREADYOPENED if = the=20 application attempts to reopen a document with ODM_MODIFYMODE = or=20 ODM_VIEWMODE that it has already opened with either of these = modes. See=20 below for one possible exception.
ODM_E_FAIL if the DMS is = unable to=20 make the document accessible for any other = reason.
ODM_E_HANDLE if=20 handle was invalid.

If the application attempts to open a document for = ODM_VIEWMODE that=20 it already has opened for ODM_VIEWMODE , then the DMS may = either return=20 the ODM_E_ALREADYOPNED error status or ODM_SUCCESS along = with=20 the previously returned temporary file specification. The DMS should = not=20 return ODM_SUCCESS in this case unless it is maintaining a = reference=20 count of the number of times this application has opened the document = for=20 ODM_VIEWMODE access. The application must call = ODMCloseDoc or=20 ODMCloseDocEx once for every time the document was successfully = opened.=20 On the last close call the DMS will delete the temporary file.=20

ODMQueryCapability

ODMSTATUS ODMQueryCapability( ODMHANDLE handle, LPCSTR lpszDmsId, = DWORD=20 function, DWORD item, DWORD flags );=20

This function is used by a client application to determine if a DMS = supports a given ODMA function, or a specific action code in = ODMActivate or a=20 specific event code in ODMSetDocEvent . It can also be used to = determine if=20 the DMS supports getting or setting a given document attribute using=20 ODMGetDocInfo or ODMSetDocInfo .=20

Parameters:=20

handle - in - A handle obtained by a previous ODMRegisterApp call.=20

lpszDmsId - in - A pointer to a null terminated string containing = the DMS=20 ID of the DMS to query. A DMS ID can be obtained by calling = ODMGetDMSList ,=20 ODMGetDMS or ODMGetDMSInfo . If this parameter is set to Null, then = the=20 default DMS is queried (the one opened with ODMRegisterApp ).=20

function - in - One of the following function ids:=20

ODM_QC_ACTIVATE ODM_QC_QUERYEXECUTE
ODM_QC_CLOSEDOC ODM_QC_QUERYGETRESULTS
ODM_QC_CLOSEDOCEX ODM_QC_SAVEAS
ODM_QC_GETALTERNATECONTENT ODM_QC_SAVEASEX
ODM_QC_GETDMSINFO ODM_QC_SAVEDOC
ODM_QC_GETDOCINFO ODM_QC_SAVEDOCEX
ODM_QC_GETDOCRELATION ODM_QC_SELECTDOC
ODM_QC_GETLEADMONIKER ODM_QC_SELECTDOCEX
ODM_QC_NEWDOC ODM_QC_SETALTERNATECONTENT
ODM_QC_OPENDOC ODM_QC_SETDOCEVENT
ODM_QC_QUERYCLOSE ODM_QC_SETDOCRELATION

item - in - Optional item, action code or event, depending on the = function=20 being queried. Specify a value of 0 to query if the DMS supports the = function.=20 If ODM_QC_ACTIVATE is specified in function , then an action value can = be=20 specified in this parameter. If ODM_QC_GETDOCINFO or ODM_QC_SETDOCINFO = is=20 specified in function , then an item code can be specified in this = parameter.=20 If function is ODM_QC_SETDOCEVENT then an event code can be specified = in item=20 . See the individual functions for the constants that can be used in = the item=20 parameter.=20

flags - in - Many ODMA functions have a flags parameter. This = parameter can=20 be used to test if a DMS supports specified input or output flags for = a=20 function. For example an application might test to see if a DMS can = support=20 unattended operations by specifying the ODM_SILENT flag here. It is = ignored if=20 the function specified in the function parameter does not have a flags = parameter. Return value:=20

ODM_SUCCESS if the DMS supports the specified function or = the=20 specified item/action/event.
ODM_E_NODMS if a DMS ID was = specified=20 in lpszDmsId which the ODMA Connection Manager could not=20 find.
ODM_E_NOSUPPORT if the DMS does not support the = function=20 specified in function .
ODM_E_ITEM if the DMS does not = support the=20 item, action code or event code specified in item . =
ODM_E_USERINT=20 if ODM_SILENT was specified in flags and the DMS cannot satisfy = the=20 function specified in function without user=20 interaction.
ODM_E_REQARG if nothing was specified in the = function=20 parameter.
ODM_E_INVARG if flags was invalid for the = function=20 specified in function .
ODM_E_HANDLE if handle was=20 invalid.
ODM_E_FAIL if the DMS was unable to process the = function=20 for other reasons.

ODMQueryClose

ODMSTATUS ODMQueryClose( ODMHANDLE handle, LPCSTR queryId )=20

This function is used by a client application to indicate that it = has=20 finished using the query and that the involved DMS(s) should release = any=20 resources and/or memory for the result set.=20

Parameters:=20

handle - in - A handle obtained by a previous ODMRegisterApp = call.=20

queryId - in - A pointer to a null-terminated string containing a = query id=20 returned by a previous call to ODMQueryExecute.=20

Return value:=20

ODM_SUCCESS on success, where upon the queryId is no longer=20 valid.
ODM_E_HANDLE if handle was = invalid.
ODM_E_FAIL if=20 one or more input values are invalid.

ODMQueryExecute =

ODMSTATUS ODMQueryExecute( ODMHANDLE handle, LPCSTR lpszQuery, = DWORD flags,=20 LPCSTR lpszDMSList, LPSTR queryId )=20

This function will pass the lpszQuery along to each DMS as = specified by the=20 flags parameter. It will return a query ID that can be used in = subsequent=20 calls to ODMQueryGetResults and ODMQueryClose . If this function is=20 successful, the calling application must eventually call ODMQueryClose = to=20 release this query.=20

Parameters:

handle - in - A handle obtained by a previous ODMRegisterApp call.=20

lpszQuery - in - The query to be processed by one or more DMSs. = Refer to=20 the Query Syntax section for the exact syntax specification.=20

flags - in - One of the following:=20

ODM_ALL - All DMS providers on this workstation.
ODM_SPECIFIC - = A set of=20 specific DMSs to run query against.

lpszDMSList - in - Valid only if value of flags is ODM_SPECIFIC . A = buffer=20 containing a list of DMSs. The format for the list is a collection of=20 null-terminated strings. The list is terminated by an empty string = (i.e.=20 "<id#1>\0<id#2>\0\0").=20

queryId - out - An id to be used for search identification to = subsequent=20 calls. This is the query ID a client application uses to communicate = with=20 Connection Manager, which in turn maps the ID to a DMS-specific query = ID. For=20 the case of multiple DMS=92s, this ID is mapped to multiple = DMS-specific query=20 IDs. Such mapping is handled by Connection Manager and is transparent = to the=20 client application. The buffer size for queryId should be at least=20 ODM_QUERYID_MAX bytes.=20

Return value:=20

ODM_SUCCESS if successful.
ODM_E_CANCEL if the user canceled the = query.
ODM_E_PARTIALSUCCESS if one or more DMSs returned a = successful=20 status and one or more DMSs return a failure.
ODM_E_HANDLE if = handle was=20 invalid.
ODM_E_FAIL if invalid data was sent in, or no DMS was = specified or=20 all DMSs failed to process the query.

ODMQueryGetResults
ODMSTATUS=20 ODMQueryGetResults( ODMHANDLE handle, LPCSTR queryId, LPSTR lpszDocId, = LPSTR=20 lpszDocName, WORD docNameLen, LPWORD pwDocCount )=20

This function will fetch pwDocCount number of documents at a time.=20

Parameters:

handle - in - A handle obtained by a previous ODMRegisterApp call.=20

queryId - in - A pointer to a null-terminated string containing a = query id=20 returned by a previous call to ODMQueryExecute.=20

lpszDocId - out - A pointer to a buffer to receive document Ids for = documents that satisfied the search referenced in queryId . This = buffer needs=20 to be at least ( ODM_DOCID_MAX * pwDocCount ) + 1 bytes in length.=20

lpszDocName - out - A pointer to a buffer to receive ODM_NAME = attribute=20 values for documents that satisfied the search referenced in queryId . = This=20 buffer needs to be at least ( docNameLen * pwDocCount ) + 1 bytes in = length.=20

docNameLen - in - The length of a document name including the=20 null-terminator.=20

pwDocCount - in/out - A pointer to a variable used to pass a = document=20 count. On input, pwDocCount contains the number of documents expected = by the=20 client application. On output, pwDocCount contains the actual number = of=20 documents returned by this function.=20

Return value:=20

ODM_SUCCESS if no error and there are more rows=20 available.
ODM_E_NOMOREDATA if there is no more data. The contents = of=20 lpszDocId , lpszDocName and docCount are undefined.
ODM_E_REQARG if = a=20 required parameter is not specified.
ODM_E_HANDLE if handle was=20 invalid.
ODM_E_FAIL if an error occurs.

ODMQueryInterface

HRESULT ODMQueryInterface( ODMHANDLE handle, LPSTR lpszDocId, = REFIID riid,=20 LPVOID FAR *ppvObj )=20

An application can use this function to get a COM interface from an = ODMA=20 provider. All ODMA providers support the IODMDocMan interface and some = support=20 IODMDocMan2 and IODMQuery . Individual DMSs may support other = interfaces as=20 well. Note that this function is prototyped in odmacom.h instead of = odma.h, so=20 that non-COM-aware applications do not have to #include the header = files that=20 define interface IDs.=20

Parameters:=20

handle - in - A handle obtained by a previous ODMRegisterApp call.=20

lpszDocId - in - An ODMA document ID or Null. If Null then the=20 application's default DMS is queried for the interface. Otherwise the = DMS that=20 created this document ID is queried.=20

riid - in - The interface to be obtained from the DMS.=20

ppvObj - out - If the requested interface is supported by the DMS = then it=20 is returned here. Otherwise ppvObj is set to Null.=20

Return value:=20

S_OK if successful.
E_INVALIDARG if handle or lpszDocId is=20 invalid.
E_NOINTERFACE if the requested interface is not supported = by the=20 DMS.
E_ACCESSDENIED if the DMS refuses the calling = application.
E_FAIL=20 if the DMS fails to initialize itself or fails for any other reason.=20

ODMRegisterApp

ODMSTATUS ODMRegisterApp( ODMHANDLE FAR *pHandle, WORD version, = LPSTR=20 lpszAppId, DWORD dwEnvData, LPVOID pReserved )=20

ODMRegisterApp registers an application with the appropriate = Document=20 Management System (DMS) and returns a session handle that can be used = in calls=20 to other ODMA functions.=20

An application normally calls this function before calling any = other ODMA=20 function. Some functions such as ODMGetDMSCount , ODMGetDMSList , = ODMGetDMS=20 and ODMSetDMS can be called before ODMRegisterApp . These are used by=20 applications that wish to control which DMS they will access when=20 ODMRegisterApp is called.=20

A task may call ODMRegisterApp more than once. Each call will = return a=20 different handle, each of which must be released with ODMUnRegisterApp = .=20

Parameters:

pHandle - out - If successful, a session handle is returned here = that can=20 be used in calls to other ODMA functions. If the registration fails = then 0 is=20 returned here.=20

version - in - Specifies the version of the API required by the=20 application. 100 should be passed to indicate version 1.0, 150 for = version=20 1.5, 200 for version 2.0, etc. The macro ODM_API_VERSION can be used = to get=20 the current version number at compile time. All versions of the ODMA = API will=20 be downward compatible, so this should be interpreted as the minimum = version=20 number that the calling application expects the DMS to support. If the = DMS=20 does not support the specified version or a higher version then it = should=20 return an error.=20

lpszAppId - in - A unique identifier for the application. The = maximum=20 length for this string is ODM_APPID_MAX , which is 16 characters = including the=20 terminating Null. The application ID cannot begin with a digit. It is=20 recommended that a Windows application use the application class name = it uses=20 in the registry as its ODMA Application ID, but this is not required.=20

dwEnvData - in - Environment data. On Windows platforms this is a = Window=20 handle for a parent window in the calling application. The DMS may use = this=20 window handle as the parent window for any dialogs or other windows it = displays in response to ODMA calls. This handle must remain valid for = the=20 duration of the ODMA session (i.e. until ODMUnRegisterApp is called).=20

pReserved - in - Reserved for future use. Must be set to Null.=20

Return value:=20

ODM_SUCCESS if successful.
ODM_E_NODMS if no Document = Management System=20 has been registered for the calling application.
ODM_E_CANTINIT if = a DMS=20 is registered for the calling application, but it fails to initialize=20 itself.
ODM_E_VERSION if the DMS does not support the requested = version of=20 the API.
ODM_E_REFUSED if the DMS has been configured to refuse = ODMA access=20 for the calling application.

This is not considered an error condition. If this status is = returned, the=20 application should simply act as if ODMA is not on the system.=20

ODMSaveAs

ODMSTATUS ODMSaveAs( ODMHANDLE handle, LPSTR lpszDocId, LPSTR = lpszNewDocId,=20 LPSTR lpszFormat, ODMSAVEASCALLBACK pcbCallBack, LPVOID pInstanceData = )=20

This function causes the DMS to return a new document ID for a = document=20 that is based on an existing document. An application would typically = call=20 this function in response to the user selecting a File Save As menu = option.=20 ODMSaveAs causes the DMS to display options to the user for selecting = the=20 destination for the new document. This might be an entirely new = document or a=20 new version of the current document. Any dialog box displayed by the = DMS=20 should be task/application modal.=20

Often the application will want to present additional options to = the user=20 at this point such as different file formats or encrypting the = document. This=20 is accomplished via the pcbCallBack parameter. ODMA implementers = should=20 provide a method for users to access this function if desired. For = example,=20 the DMS may show a dialog that includes an Options button. If the user = clicks=20 this button, the DMS would call the application's callback function = which=20 would give the application a chance to display other save options.=20

Note that following a successful call to ODMSaveAs the calling = application=20 may have two different document IDs to work with. This is different = than the=20 situation with ODMSaveDoc where the new ID replaces the old one in the = current=20 session. The state of the document specified by the old ID remains the = same=20 after the call. The document specified by the new ID will be in the = closed=20 state following the call. A typical sequence of operations an = application=20 might follow in response to the user selecting File | Save As would = be:=20

  1. Application passes the currently open document's ID to ODMSaveAs = . If an=20 empty string is returned for the new ID, then the application should = call=20 ODMSaveDoc with the current document ID to indicate to the DMS that = document=20 should be saved in the document repository. If a new ID for the = document is=20 returned then continue with the steps below.=20
  2. Application calls ODMOpenDoc on the new ID. This returns a new = filename=20 for the document.=20
  3. Application saves the document to the new filename and then = calls=20 ODMSaveDoc on the new ID to indicate to the DMS that the new = document should=20 be saved in the document repository.=20
  4. Application calls ODMCloseDoc on the old ID.=20
  5. The application can now forget about the old ID and use the new = ID for=20 all subsequent operations on the file. When the current session is = completed=20 it will call ODMCloseDoc on the new ID.

Parameters:=20

handle - in - A handle obtained by a previous ODMRegisterApp call.=20

lpszDocId - in - A null-terminated document ID. This is typically = obtained=20 by a call to ODMSelectDoc , ODMSelectDocEx or ODMNewDoc . This = document may or=20 may not be open at the time that ODMSaveAs is called. Its open status = will=20 remain the same after this call.=20

lpszNewDocId - out - A pointer to a buffer where the DMS will = return the ID=20 of the new document. This buffer must be at least ODM_DOCID_MAX bytes = in=20 length. If successful then a null-terminated document ID will be = returned=20 here, unless the document is saved with the current ID. In this case = the first=20 byte of this buffer will be set to Null and 0 will be returned. = Otherwise the=20 contents of the buffer will be undefined.=20

lpszFormat - in - A null-terminated string naming the format in = which the=20 application expects to save the document. This may be passed as a = parameter to=20 the pcbCallBack function which may return a different format. Refer to = the=20 Document Format Names section for information on how file formats are=20 identified in ODMA.=20

pcbCallBack - in - A pointer to a callback function that can be = used by the=20 application to make other saving options available to the user. Any UI = presented by this callback function should be task modal. The function = should=20 return a pointer to a format string which may or may not be the same = as the=20 original format string. This parameter may be null if the application = does not=20 wish to present any options. Under Microsoft Windows the = procedure-instance=20 address of the callback function (obtained from MakeProcInstance ) = should be=20 used. The callback function's interface is as follows:=20

LPSTR __cdecl SaveAsCallBack(DWORD dwEnvData, LPSTR lpszFormat, = LPVOID=20 pInstanceData)=20

dwEnvData - in - Environment data. On Windows platforms this is a = Window=20 handle for a parent window to associate with the callback function's = display.=20 If the DMS displayed a dialog in response to the ODMSaveAs call then = it should=20 pass the window handle for that dialog. Otherwise it should pass the = window=20 handle obtained from the ODMRegisterApp call. The callback function = may use=20 this window handle as the parent window for any dialogs or other = windows it=20 displays.=20

lpszFormat - The currently selected document format. The DMS should = allocate at least ODM_FORMAT_MAX for this buffer. If the application = handling=20 the callback wishes to update this DMS buffer and return its pointer = back as=20 the value of the callback, then it should take care to not overwrite = the=20 buffer=92s length.=20

pInstanceData - The instance data passed from the calling = application.=20

pInstanceData - in - A pointer to caller context information that = will be=20 passed to the pcbCallBack function. This data will not be accessed by = ODMA.=20

Return value:=20

ODM_SUCCESS if successful.
ODM_E_CANCEL if the user cancels the = creation=20 of the new document.
ODM_E_DOCID if the document ID is invalid or = refers to=20 a document that no longer exists.
ODM_E_APPSELECT if the user = selected to=20 save the document as a non-profiled document.
ODM_E_OFFLINE if the = DMS has=20 no local data store and is off-line from its server; generally the = caller=20 should treat this the same as ODM_E_APPSELECT .
ODM_E_FAIL if the = DMS is=20 unable to display its Save As dialog box or create the new=20 document.
ODM_E_HANDLE if handle was invalid.

ODMSaveAsEx

ODMSTATUS ODMSaveAsEx( ODMHANDLE handle, LPSTR lpszDocId, LPSTR=20 lpszNewDocId, LPSTR lpszFormat, ODMSAVEASCALLBACK pcbCallBack, LPVOID=20 pInstanceData, LPDWORD pdwFlags )=20

The ODMSaveAsEx function extends ODMSaveAs by adding a pdwFlags = parameter=20 to allow for unattended document creation. It also can be called = without first=20 calling ODMNewDoc .=20

This function causes the DMS to return a new document ID for a = document=20 that is based on an existing document. An application would typically = call=20 this function in response to the user selecting a File Save As menu = option.=20 ODMSaveAsEx causes the DMS to display options to the user for = selecting the=20 destination for the new document. This might be an entirely new = document or a=20 new version of the current document. Any dialog box displayed by the = DMS=20 should be task/application modal.=20

Often the application will want to present additional options to = the user=20 at this point such as different file formats or encrypting the = document. This=20 is accomplished via the pcbCallBack parameter. ODMA implementers = should=20 provide a method for users to access this function if desired. For = example,=20 the DMS may show a dialog that includes an Options button. If the user = clicks=20 this button, the DMS would call the application's callback function = which=20 would give the application a chance to display other save options.=20

Note that following a successful call to ODMSaveAsEx the calling=20 application may have two different document IDs to work with. This is=20 different than the situation with ODMSaveDoc or ODMSaveDocEx where the = new ID=20 replaces the old one in the current session. The state of the document = specified by the old ID remains the same after the call. The document=20 specified by the new ID will be in the closed state following the = call. A=20 typical sequence of operations an application might follow in response = to the=20 user selecting File | Save As would be:=20

  1. Application passes the currently open document's ID to = ODMSaveAsEx . If=20 an empty string is returned for the new ID, then the application = should call=20 ODMSaveDoc or ODMSaveDocEx with the current document ID to indicate = to the=20 DMS that document should be saved in the document repository. If a = new ID=20 for the document is returned then continue with the steps below.=20
  2. Application calls ODMOpenDoc on the new ID. This returns a new = filename=20 for the document.=20
  3. Application saves the document to the new filename and then = calls=20 ODMSaveDoc or ODMSaveDocEx on the new ID to indicate to the DMS that = the new=20 document should be saved in the document repository.=20
  4. Application calls ODMCloseDoc or ODMCloseDocEx on the old ID.=20
  5. The application can now forget about the old ID and use the new = ID for=20 all subsequent operations on the file. When the current session is = completed=20 it will call ODMCloseDoc or ODMCloseDocEx on the new ID.

Parameters:

handle - in - A handle obtained by a previous ODMRegisterApp call.=20

lpszDocId - in - A null-terminated document ID. This is typically = obtained=20 by a call to ODMSelectDoc , ODMSelectDocEx or ODMNewDoc . This = document may or=20 may not be open at the time that ODMSaveAsEx is called. Its open = status will=20 remain the same after this call.=20

This lpszDocId parameter can optionally be set to NULL if the = calling=20 application did not first call ODMNewDoc . In this case, the DMS will = return a=20 document ID in the buffer specified in lpszNewDocId .=20

lpszNewDocId - out - A pointer to a buffer where the DMS will = return the ID=20 of the new document. This buffer must be at least ODM_DOCID_MAX bytes = in=20 length. If successful then a null-terminated document ID will be = returned=20 here, unless the document is saved with the current ID. In this case = the first=20 byte of this buffer will be set to Null and 0 will be returned. = Otherwise the=20 contents of the buffer will be undefined.=20

lpszFormat - in - A null-terminated string naming the format in = which the=20 application expects to save the document. This may be passed as a = parameter to=20 the pcbCallBack function which may return a different format. Refer to = the=20 Document Format Names section for information on how file formats are=20 identified in ODMA.=20

pcbCallBack - in - A pointer to a callback function that can be = used by the=20 application to make other saving options available to the user. Any UI = presented by this callback function should be task modal. The function = should=20 return a pointer to a format string which may or may not be the same = as the=20 original format string. This parameter may be null if the application = does not=20 wish to present any options. Under Microsoft Windows the = procedure-instance=20 address of the callback function (obtained from MakeProcInstance) = should be=20 used. The callback function's interface is as follows:=20

LPSTR __cdecl SaveAsCallBack(DWORD dwEnvData, LPSTR lpszFormat, = LPVOID=20 pInstanceData)=20

dwEnvData - in - Environment data. On Windows platforms this is a = Window=20 handle for a parent window to associate with the callback function's = display.=20 If the DMS displayed a dialog in response to the ODMSaveAsEx call then = it=20 should pass the window handle for that dialog. Otherwise it should = pass the=20 window handle obtained from the ODMRegisterApp call. The callback = function may=20 use this window handle as the parent window for any dialogs or other = windows=20 it displays.=20

lpszFormat - The currently selected document format. The DMS should = allocate at least ODM_FORMAT_MAX for this buffer. If the application = handling=20 the callback wishes to update this DMS buffer and return its pointer = back as=20 the value of the callback, then it should take care to not overwrite = the=20 buffer=92s length.=20

pInstanceData - The instance data passed from the calling = application.=20

pInstanceData - in - A pointer to caller context information that = will be=20 passed to the pcbCallBack function. This data will not be accessed by = ODMA.=20

pdwFlags - in/out - A pointer to a variable containing flags used = on both=20 input and output. On input, 0 or the following flag:=20

ODM_SILENT - The DMS should not require user interaction while = satisfying=20 the call. If the call cannot be satisfied without user interaction = then an=20 error should be returned. If the DMS has enough information to create = a new=20 document then it should return ODM_SUCCESS .=20

ODMA 2.0 does not define any output flags at this time.=20

Return value:=20

ODM_SUCCESS if successful.
ODM_E_CANCEL if the user cancels the = creation of the new document.
ODM_E_DOCID if the document ID is = invalid or=20 refers to a document that no longer exists.
ODM_E_APPSELECT if the = user=20 selected to save the document as a non-profiled = document.
ODM_E_OFFLINE if=20 the DMS has no local data store and is off-line from its server; = generally the=20 caller should treat this the same as ODM_E_APPSELECT = .
ODM_E_USERINT if the=20 ODM_SILENT flag was specified and the DMS does not support document = creation=20 without user interaction or the DMS does not have enough information = to create=20 the document without user interaction.
ODM_E_FAIL if the DMS is = unable to=20 display its Save As dialog box or create the new = document.
ODM_E_HANDLE if=20 handle was invalid.

ODMSaveDoc

ODMSTATUS ODMSaveDoc( ODMHANDLE handle, LPSTR lpszDocId, LPSTR = lpszNewDocId=20 )=20

This function tells the DMS that the document should be saved to = the=20 document repository. An application would typically call this function = after=20 saving changes to the temporary file returned by ODMOpenDoc . A new = document=20 ID is returned to the application which should be used for all = subsequent=20 operations on the document. This ID replaces the previous document ID = in the=20 current session. The new ID may or may not be the same as the original = ID. It=20 will usually be the same unless the DMS saved the document as a new = version or=20 as a new document. If the new ID is different from the previous ID = then the=20 previous ID cannot be used subsequently without doing an ODMOpenDoc on = it.=20
Parameters:=20

handle - in - A handle obtained by a previous ODMRegisterApp call.=20

lpszDocId - in - A document ID. This is typically obtained by a = call to=20 ODMSelectDoc or ODMNewDoc . This document must have been previously = opened in=20 modify mode by a call to ODMOpenDoc .=20

lpszNewDocId - out - A pointer to a buffer where the DMS will = return the=20 new ID of the document. This buffer must be at least ODM_DOCID_MAX = bytes in=20 length. If successful then a null-terminated document ID will be = returned=20 here. Otherwise the contents of the buffer will be undefined.=20

Return value:=20

ODM_SUCCESS if successful.
ODM_E_NOOPEN if the document wasn=92t = previously opened with ODMOpenDoc .
ODM_E_OPENMODE if the document = was not=20 previously opened in modifiable mode.
ODM_E_FAIL if the DMS is = unable to=20 save the document to the document repository.
ODM_E_HANDLE if = handle was=20 invalid.

ODMSaveDocEx

ODMSTATUS ODMSaveDocEx( ODMHANDLE handle, LPSTR lpszDocId, LPSTR=20 lpszNewDocId, LPDWORD pdwFlags )=20

This function tells the DMS that the document should be saved to = the=20 document repository. ODMSaveDocEx is basically the same as ODMSaveDoc = , except=20 it has a pwdFlags parameter. This provides the application with more = control=20 during the document creation or save process. There is an ODM_SILENT = flag that=20 facilitates unattended document creation or saving. Some DMSs display = a user=20 interface when saving a document (i.e. to have the user specify = revision or=20 version information). This flag allows the calling application to = suppress=20 this UI if necessary or to influence it, if the DMS should allow that. =

An application would typically call this function after saving = changes to=20 the temporary file returned by ODMOpenDoc . A new document ID is = returned to=20 the application which should be used for all subsequent operations on = the=20 document. This ID replaces the previous document ID in the current = session.=20 The new ID may or may not be the same as the original ID. It will = usually be=20 the same unless the DMS saved the document as a new version or as a = new=20 document. If the new ID is different from the previous ID then the = previous ID=20 cannot be used subsequently without doing an ODMOpenDoc on it.=20

Parameters:=20

handle - in - A handle obtained by a previous ODMRegisterApp call.=20

lpszDocId - in - A document ID. This is typically obtained by a = call to=20 ODMSelectDoc or ODMNewDoc . This document must have been previously = opened in=20 modify mode by a call to ODMOpenDoc .=20

lpszNewDocId - out - A pointer to a buffer where the DMS will = return the=20 new ID of the document. This buffer must be at least ODM_DOCID_MAX = bytes in=20 length. If successful then a null-terminated document ID will be = returned=20 here. Otherwise the contents of the buffer will be undefined.=20

pdwFlags - in/out - A pointer to a variable containing flags used = on both=20 input and output. On input, 0 or one or more of the following flags:=20

ODM_SILENT - The DMS should not require user interaction while = satisfying=20 the call. If the call cannot be satisfied without user interaction = then an=20 error should be returned.=20

ODM_VERSION_SAME - If saving an existing document the DMS should = keep the=20 version information the same. If the DMS does not support versioning = this flag=20 should be ignored.=20

ODM_VERSION_MAJOR - If saving an existing document the DMS should = increment=20 the major version number. If the DMS displays a dialog this flag is an = indication of how the dialog might be initialized. If the DMS does not = support=20 versioning this flag should be ignored.=20

ODM_VERSION_MINOR - If saving an existing document the DMS should = increment=20 the minor version number. A DMS that doesn=92t support minor versions = should=20 just treat this like a major version. If the DMS displays a dialog = this flag=20 is an indication of how the dialog might be initialized.=20

Upon return, one of