The DMA Integration Model defines how DMA components are assembled, how these components interact and how client applications interact with these components.
The principal DMA components visible to DMA client applications are as follows:
Additional components participating in the integration infrastructure are follows:
The System Manager is a COM object that can create new DMA System objects, which in turn can create new DMA DocSpace objects.
DMA Text Ordering service objects enable text collation logic to be decoupled from DMA System or DocSpace object implementations.
DMA OIID Parser service objects enable OIID parsing logic to be decoupled from the DMA System Manager implementation.
DMA Scope Factory service objects enable merged scope creation to be decoupled from the DMA System object implementation.
The System Manager is implemented in an operating environment dependent manner. AIIM intends to provide System Manager implementations for popular environments including Microsoft Windows 32 and various Unix platforms. The mechanism that clients utilize to create System Manager objects is both platform and language specific.
DMA service providers implement the remaining objects. A uniform (although platform specific) mechanism is defined by which service providers can be called upon to deliver instances of the objects they implement.
The following UML figure illustrates the relationships between the DMA Integration model components.
Figure -1 DMA Integration Model Components
DMA doesn’t specify a traditional functional client API. Instead, the DMA client API can be viewed as one function which delivers System Manager objects and a set of the methods in COM interfaces delivered by those System Manager objects which in turn deliver other objects.
Similarly, DMA doesn’t specify a traditional functional server side SPI. Instead, DMA specifies a set of COM interfaces that DMA Service Objects must implement, COM interfaces for registering DMA Service Objects and a single function for activating a DMA Service Object.
DMA also doesn’t impose restrictions on the distribution of DMA implementation other than requiring that the initial means of obtaining the initial System Manager object be callable by the client application. As the rest of the client’s interaction is via method calls on COM interfaces, the underlying implementation of any of the DMA COM objects may be remote from the client’s point of presence.
The Client View: Access to DMA Systems and Document Spaces
Application Connection to the System Manager
A DMA application obtains (connects to) a System Manager object by a well known mechanism. The only currently defined mechanism supports C and C++ client implementations on the Win32 platform. Virtually identical mechanisms are likely to be specified for C and C++ applications on other platforms. This mechanism may or may not be accessible from other implementation languages; where it is not, DMA may define alternative mechanisms in the future.
For DMA 1.0 on the Win32 platform, a System Manager object is obtained by calling the dmaConnectSystemManager function, which is exported by the DMA10.DLL dynamic link library. On other platforms, the same function will be used, although the packaging of that function (e.g. shared library, static library, etc.) is not currently defined.
The following is the general signature for dmaConnectSystemManager.
DmaRC dmaConnectSystemManager ( pDmaVoid pEnvInfo, pDmaOpaqueString pProfile, Dmapv pIMalloc, DmaInteger32 lCharSetEncodingID, pDmaString pLocaleName, REFIID riid, pDmapv ppISysMgr)
The following sections discuss how an application selects values for each of these parameters.
The pEnvInfo parameter should be NULL or operating environment specific data that is required to define the execution environment that the System Manager object must operate within. It’s required value will be specified for each operating environment System Manager implementation. For Win32, this parameter should be NULL.
The pProfile parameter should be NULL or operating environment specific data that is required to locate System Manager configuration information such as a registry key name. Allowable values will be specified for each operating environment System Manager implementation. For Win32, this parameter should be NULL.
The pIMalloc parameter should be NULL or a reference to a COM interface of an object that supplies an IMalloc interface. If this parameter is NULL, the System Manager provides a default IMalloc implementation that is used throughout the lifetime of the System Manager and any of its children. For the Win32 platform, the default implementation is that returned by the CoGetMalloc API.
The System Manager and all of its children will employ this IMalloc interface in constructing all storage structures delivered as output parameters from methods on their interfaces. This applies any time that an interface delivers an output pointer that is not a pointer to an interface, including pointers embedded in the data reached by such outputs (hereafter referred to as non-interface output pointers). In addition, any interfaces supplied as parameters to methods on the System Manager or its must deliver non-interface outputs that were allocated with this same IMalloc interface.
The lCharSetEncodingID parameter specifies a character set encoding that the System Manager object and all its children will utilize for any DmaString parameters. Its value will typically specify Unicode when operating in a Microsoft COM environment.
The pLocaleName parameter specifies the name of a locale that the System Manager object and any System objects returned via the System Manager’s EnumerateSystems method are requested to operate within. A NULL value indicates that the System Manager and System objects returned from EnumerateSystems may choose a default locale to operate within based upon implementation choices or operating environment information, for example the current Windows or Unix locale.
The DMA Internationalization and Localization chapter discusses character set encoding and locale names in more detail.
The riid parameter must be a reference to an interface identifier (IID) for an interface supported by a System Manager object. This will typically be a reference to IID_IdmaSystemManager.
The ppISysMgr parameter is used to return a reference to the requested interface on a System Manager object.
If the dmaConnectSystemManager function is successful, a DMARC_SUCCESS return code value is returned, otherwise one of a small set of error return codes will be returned.
A DMA application obtains (connects to) a DMA System object using methods on the System Manager object’s IdmaSystemManager interface. The EnumerateSystems method is used to return an IdmaEnumOfObject interface that can be used to enumerate all of the System objects that a System Manager can connect to. A specific System can be connected to using the ConnectSystem method.
DMA Systems are the first full fledged DMA object that an application encounters. They support the IdmaObject and IdmaProperties interfaces and as such exist within a DMA class hierarchy, have properties and are described by DMA meta-data.
The properties specific to a System object include a Display Name, a Descriptive Text, a list of supported Locale Names and the current Locale Name. The values of the Display Name and Descriptive Text properties would typically have values based upon the value of the current Locale Name property.
The System objects returned by the EnumerateSystems and ConnectSystem methods may represent unauthenticated connections to DMA systems. If the system requires user authentication, it will indicate so by providing an IdmaAuthentication interface on the System object.
Applications should determine whether authentication is required before attempting to invoke any methods other than those used to browse the object’s property values and meta-data. If the interface is not present, the object does not require explicit authentication. Otherwise authentication can be achieved using methods available on the IdmaAuthentication interface. The use of these methods is described in more detail in a later section.
Object valued properties cannot be accessed if the System object is in an unauthenticated state. Attempts to access an object valued property in an unauthenticated state will yield a DMARC_NOT_AUTHENTICATED return code.
A DMA application obtains (connects to) a DMA DocSpace object using methods on the System object’s IdmaSystem interface. The EnumerateDocSpaces method is used to return an IdmaEnumOfObject interface that can be used to enumerate all of the DocSpace objects that a System can connect to. A specific DocSpace can be connected to using the ConnectDocSpace method.
The properties specific to a DocSpace object include a Display Name, a Descriptive Text, a list of supported Locale Names and the current Locale Name. The values of the Display Name and Descriptive Text properties would typically have values based upon the value of the current Locale Name property.
The DocSpace objects returned by the EnumerateDocSpaces and ConnectDocSpace methods may represent unauthenticated connections to DMA document spaces. If the document space requires user authentication, it will indicate so by providing an IdmaAuthentication interface on the DocSpace object.
Applications should determine whether authentication is required before attempting to invoke any methods other than those used to browse the object’s property values and meta-data. If the interface is not present, the object does not require explicit authentication, otherwise authentication can be achieved using methods available on the IdmaAuthentication interface. The use of these methods is described in more detail in a later section.
Object valued properties cannot be accessed if the DocSpace object is in an unauthenticated state. Attempts to access an object valued property in an unauthenticated state will yield a not authenticated return code.
Applications may use DMA DocSpace objects to instantiate objects managed by the document space. These objects may be instantiated from a DocSpace object using DMA addressability, navigation and searching which are discussed in the DMA Object Model and DMA Query Model sections of this document.
The following figure and notes describe how character set encoding and locale name data affect the DMA client integration model.
Figure -2 DMA Integration Model and Localization Considerations
1. The client gets an IdmaSystemManager interface pointer by calling a well-known exported dmaConnectSystemManager entry point on the System Manager shared library. Via parameters to dmaConnectSystemManager, the client establishes the character set encoding to be used within the context of the System Manager object, and optionally a locale name.
2. The client application calls the IdmaSystemManager::EnumerateSystems() method to enumerate visible systems. This method returns an enumerator object that supplies unauthenticated System objects.
3. Alternatively, the client connects to a system by calling the IdmaSystemManager::ConnectSystem() method specifying one of the locale names that is supported by the system. The list of applicable locale names may be established by a prior call to IdmaSystemManager::EnumerateSystems and subsequent inspection of the System object’s Local Names property.
At this point in time, the system object has been created and its CharSetEncodingID and LocaleName properties may be interrogated. Their values will correspond to the system’s registered character set encoding and the locale name specified to IdmaSystemManager::ConnectSystem().
4. The client invokes the IdmaSystem::EnumerateDocSpaces method to enumerate the Document Spaces that a DMA system supports. This method returns an enumerator object that supplies unauthenticated DocSpace objects.
5. Alternatively, the client invokes the IdmaSystem::ConnectDocSpace() method specifying one of the locale names supported by the Document Space. The list of applicable locale names may be established by a prior call to IdmaSystem::EnumerateDocSpaces and subsequent inspection of the DocSpace object’s Local Names property.
At this point in time, a DocSpace object has been created and its LocaleName property may be interrogated. Its value will be the locale name that was specified to the IdmaSystem::ConnectDocSpace() method.
Behind the scenes, IdmaSystem::ConnectDocSpace() activated the Document Space service object by invoking the DMA_GetServiceObject() function, specifying the DMA system’s character set encoding and optionally a locale name, which created a DocSpace object and returned the IdmaDocSpace COM interface pointer.
DMA factors authentication into a separate IdmaAuthentication interface which may be present on DMA System and DocSpace objects. Typically, user authentication is performed by invoking the AuthenticateUser method, which implements an authentication model derived from the ODBC SQLBrowseConnect model.
DMA authentication is based upon an iterative stateless exchange of information between the client and System or Document Space, hereafter both are referred to as the service. The client supplies authentication parameters to the service via a DmaString parameter. If the service requires additional authentication parameters, the service provides the client with a DmaString parameter that describes the additional authentication parameters. This exchange typically starts with the client providing the service an empty authentication parameter string and iteratively refining it’s authentication parameter string until successfully authenticated or a failure is detected.
DMA currently defines two mechanisms that DMA System and Document Space implementations may use to implement authentication. DMA System and Document Space providers are encouraged to use one or both of these mechanisms instead of inventing equivalent mechanisms. Use of these documented mechanisms will increase interoperability by decreasing the need for out of band agreements between DMA application providers and DMA System and Document Space providers. The authentication mechanism is extensible; DMA System and Document Space providers are free to extend the authentication mechanism as required for their particular need.
The DMA Authentication Protocol
The DMA Authentication mechanism is best described as a protocol. The client submits a request message and the service responds with a response message. Each of these messages is encoded in a DmaString and syntactically conforms to the following BNF syntax based upon the ODBC SQLBrowseConnect syntax:
request-message ::= connection-string
response-message ::= connection-string
connection-string ::= attribute[";" connection-string]
attribute ::= [ "*" ] keyword "=" value
keyword ::= dma-keyword | provider-keyword
dma-keyword ::= { "SCHEME" | "UID" | "PWD" |"KRB-VERSION" | "KRB-PRINCIPAL" |"KRB-TICKET" | "KRB-AUTH" } [ ":" localized-identifier ]
provider-keyword ::= identifier [ ":" localized-identifier ]
value ::= "{" value-list "}" | "?" | identifier
value-list ::= identifier [ ":" localized-identifier ][ "," value-list ]
identifier and localized-identifier consist of one or more characters. keyword is to be case insensitive.
An asterisk preceding a keyword indicates that the keyword is optional and need not be present in the next request message.
DMA Authentication Schemes
The service response to an empty request message indicates which DMA authentication schemes the service supports. DMA 1.0 defines two authentication schemes and allows providers to extend the set of DMA authentication schemes. The DMA-BASIC scheme provides for a typical user-id and password based authentication. The DMA-KERBEROS scheme provides a mechanism for the client to provide the service with a Kerberos ticket and authenticator.
The following examples illustrate Authenticate method calls by showing input string, output string and return code values.
An initial Authenticate method call is used to determine which authentication schemes are supported:
Input string = "" or NULL
Output string = "SCHEME={DMA-BASIC,DMA-KERBEROS,<other>}"
Return Code = DMARC_NEED_MORE_DATA
Note: the service responds with one or more schemes. <other> denotes a scheme not standardized by DMA and must not start with the "DMA-" prefix.
DMA-BASIC Authentication
The Client selects the DMA-BASIC scheme:
Input string = "SCHEME=DMA-BASIC"
Output string = "SCHEME=DMA-BASIC;UID:UserName=?;PWD:Password=?"
Return Code = DMARC_NEED_MORE_DATA
The Client provides user-id and password:
Input string = "SCHEME=DMA-BASIC;UID=Joe DMA;PWD=DMA4ME"
Output string = NULL
Return Code = DMARC_SUCCESS
The DMARC_SUCCESS return code indicates that the user has been successfully authenticated.
DMA-KERBEROS Authentication
The DMA-KERBEROS scheme supports different versions of Kerberos. A Kerberos scheme authentication message exchange follows:
The client selects the DMA-KERBEROS scheme:
Input string = "SCHEME=DMA-KERBEROS"
Output string = "SCHEME=DMA-KERBEROS;KRB-VERSION={4,5,DCE}"
Return Code = DMARC_NEED_MORE_DATA
The client selects the DMA-KERBEROS version DCE:
Input string = "SCHEME=DMA-KERBEROS;KRB-VERSION=DCE"
Output string = "SCHEME=DMA-KERBEROS;KRB-VERSION=DCE;KRB-PRINCIPAL=DmaSystem@realm;KRB-AUTH=?;KRB-TICKET=?"
Return Code = DMARC_NEED_MORE_DATA
The response supplies the client with a Kerberos principal identifier via the KRB-PRINCIPAL value and requests that the client supply an appropriate Kerberos Authenticator and Ticket via the KRB-AUTH and KRB-TICKET values respectively.
The Client responds with an appropriate authenticator and ticket:
Input string = "SCHEME=DMA-KERBEROS;KRB-VERSION=DCE;KRB-PRINCIPAL= DmaSystem@realm;KRB-AUTH=<Base-64>;KRB-TICKET=<Base-64>"
Output string = NULL
Return Code = DMA_SUCCESS
where <Base-64> is a Base64 encoding per RFC 1521 of the Kerberos Authenticator and Ticket encrypted values.
Encryption
In DMA 1.0, there is no mechanism to support end-to-end encryption of authentication information using the DMA-BASIC scheme. It is reasonable for a distributed DMA middleware to encrypt the connection strings such that they never appear in the clear on a network. The current model requires that the DMA middleware decrypt the connection string before presenting it to a Document Space Service Object or returning it to a client. As such, the authentication information will at least be transiently stored in the clear by the DMA middleware at the Document Space Service Object and client points of presence.
DMA 1.0 also provides a mechanism that enables System and DocSpace Service Objects to implement authentication without any caller supplied parameters through the use of the AutoAuthenticateUser method. Possible implementations of this method could be predicated upon a client application’s environmental state or an earlier successful authentication.
A client application has control over automatic authentication in that it may choose to attempt automatic authentication by invoking the AutoAuthenticateUser method or utilize an interactive authentication mechanism by invoking the AuthenticateUser method.
Identifying and Accessing Persistable Document Space Objects
DMA objects with persistent state have non-null Object Instance ID (OIID) property values. DMA OIIDs are defined using an Uniform Resource Locator (URL) syntax and are intended to be useable as Internet URLs and can be encapsulated in ODMA Document IDs.
DMA 1.0 OIIDs consist of two mandatory GUIDs, one that is a DMA System ID, and another that is a DMA DocSpace ID, along with a document space specific object identifier. If the document space uses GUIDs as its internal object identifier or maintains a GUID association with its internal object identifier, it may expose this Object ID in the DMA OIID.
Methods for extracting the DMA System ID, DocSpace ID, and optional Object ID exist on the IdmaOIID interface which is required to be supported on the System Manager object. These methods can be used along with other DMA methods to instantiate a DMA object given its OIID. The following illustrates one possible object instantiation mechanism:
DMA OIID Syntax Specification
This section defines the syntax of DMA Object Instance IDs (OIIDs) using Internet URL conventions and defines how DMA OIIDs are to be encapsulated in ODMA Document Ids.
DMA OIIDs are considered logically to be an Uniform Resource Locator (URL) to a persistent DMA object. A DMA client application can get an in-memory instance of a persistent DMA object when presented with a DMA OIID. Implicit in this assumption is that the client application can:
DMA OIIDs can be easily exchanged by client applications in a manner similar to an HTTP URL. For instance, an application should be able to embed a DMA OIID in an e-mail message or a database. While there has been some discussion that it may be preferable for DMA OIIDs to be presentable in a human readable form, there is no existing requirement for this. Likewise, there is no existing requirement that they be sufficiently short for a human to memorize or manually record, e.g. write it down on paper.
The DMA URL Scheme
This proposal defines DMA OIIDs as a DMA URL scheme (consistent with RFC 1738) and as ODMA encapsulated DMA URLs. DMA URLs describe the identity of a DMA object and a mechanism exists to locate a DMA object in a hierarchical manner relative to a DMA System and DMA DocSpace. The informal syntax for a DMA URL is:
dma://[<dma pop>]/<system id>/<docspace id>/<object id>[;guid=<object guid>]
NLS character set issues would have been introduced if the System and DocSpace were encoded as human readable names in the DMA URL. For this reason, the System and DocSpace DmaIds (GUIDs) are utilized instead of the human readable names so as to avoid character set and name stability problems.
Following this line of reasoning, the syntax for the OIID components is:
<dma pop> := <host name>
<system id> ::= <Textualized System DmaId>
<docspace id> ::= <Textualized DocSpace DmaId>
<object id> ::= <Printable ASCII per HTTP URL conventions>
<object guid> ::= <Textualized Object DmaId>
The <dma pop> (read DMA Point of Presence) is a host name (e.g. library.xyz.com) that can be optionally present in the DMA OIID. Its purpose is to provide a DMA client with a name of an Internet host that most likely can connect to an OIID’s DMA System and DMA DocSpace. The host name may include a userid and password per Internet URL conventions. The "file" and proposed "ldap" URL schemes provide precedence for this URL component being optional.
At present, connection to a remote DMA point of presence is not specified using a DMA API or protocol. DMA definition of an application protocol would be required in order to perform this type of connection and as such is outside of the DMA 1.0 scope of effort. DMA 1.0 requires the <dma pop> to not be present in OIIDs generated by DMA DocSpaces and that the <dma pop> field be ignored upon presentation to a DMA 1.0 system.
The <system id> is the DMA GUID used to register the DMA System that generated the OIID. It is considered a hint in that a DMA DocSpace may be accessible from multiple DMA Systems. Any DMA System that supports the DMA DocSpace <docspace id> may suffice for accessing the persistent object referenced by the OIID, however the system <system id> is considered the best choice since it was known to work at some time in the past.
The <object id> is any sequence of data encoded into an allowed subset of ASCII according to the rules governing Internet URLs. The "/", ";" and "?" characters (and a few others) are reserved for use by the DMA URL scheme and cannot appear in the <object id> (they must be escaped). Beyond the encoding rules, the structure of the <object id> is determined entirely by the underlying Document Space implementation.
If a Document Space maintains a DMA GUID for a particular object, it is encouraged to expose that object GUID in its DMA URL using the optional ";guid=<object guid>" syntax.
DMA URL Examples:
ODMA Encapsulation
It has been proposed to the ODMA SPT that the vendor name "DMA" be reserved for encapsulation of DMA URLs in ODMA Document IDs. An encapsulated DMA ID conforms to the following syntax:
::ODMA\DMA\<DMA OIID>
This encapsulation enables ODMA Document IDs to be treated by DMA implementations as DMA OIIDs from an input parameter perspective. Any method that takes a pDmaOIID input parameter will handle either the DMA URL form or the ODMA encapsulated DMA URL form. DMA implementations will not generate the ODMA encapsulated DMA URL form of an OIID as a return parameter.
Note: ODMA Document Ids are encoded using the "native character set of the system", e.g. Unicode in Windows 32. DMA OIIDs are always encoded in US-ASCII. As such, character set translation will likely need to occur in an ODMA/DMA implementation above the DMA API.
BNF for DMA URLs
This is a BNF-like description of the DMA OIID Uniform Resource Locator syntax, using the conventions of RFC822, except that "|" is used to designate alternatives, and brackets [] are used around optional or repeated elements. Briefly, literals are quoted with "", optional elements are enclosed in [brackets], and elements may be preceded with <n>* to designate n or more repetitions of the following element; n defaults to 0.
dmaurl = "dma://" [login] "/" dmasystem "/"
dmadocspace "/" dmaobjectid [ dmaobjectguid ]
dmasystem = dmaguid
dmadocspace = dmaguid
dmaobjectid = oidchars
dmaobjectguid = ";guid=" dmaguid
dmaguid = 1*dmaguidchar
dmaguidchar = hex | "-"
oidchars = *oidchar
oidchar = alpha | digit | safe | ":" | "@" | "&" | "="
; URL schemeparts for ip based protocols:
login = [ user [ ":" password ] "@" ] hostport
hostport = host [ ":" port ]
host = hostname | hostnumber
hostname = *[ domainlabel "." ] toplabel
domainlabel = alphadigit | alphadigit *[ alphadigit | "-" ] alphadigit
toplabel = alpha | alpha *[ alphadigit | "-" ] alphadigit
alphadigit = alpha | digit
hostnumber = digits "." digits "." digits "." digits
port = digits
user = *[ uchar | ";" | "?" | "&" | "=" ]
password = *[ uchar | ";" | "?" | "&" | "=" ]
urlpath = *xchar
; Miscellaneous definitions
lowalpha = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" |
"i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" |
"q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" |
"y" | "z"
hialpha = "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" |
"J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" |
"S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z"
alpha = lowalpha | hialpha
digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" |
"8" | "9"
safe = "$" | "-" | "_" | "." | "+"
extra = "!" | "*" | "'" | "(" | ")" | ","
national = "{" | "}" | "|" | "\" | "^" | "~" | "[" | "]" | "`"
punctuation = "<" | ">" | "#" | "%" | <">
reserved = ";" | "/" | "?" | ":" | "@" | "&" | "="
hex = digit | "A" | "B" | "C" | "D" | "E" | "F" |
"a" | "b" | "c" | "d" | "e" | "f"
escape = "%" hex hex
unreserved = alpha | digit | safe | extra
uchar = unreserved | escape
xchar = unreserved | reserved | escape
digits = 1*digit
DMA System, DocSpace, Text Ordering, OIID Parser and Scope Factory implementations are types of DMA Service Objects. The DMA Service Object model provides a simple operating environment neutral mechanism for registering service providers and a uniform (although platform dependent) mechanism for the System Manager or a service object to obtain instances of other service objects.
DMA is silent about how DMA Service Object implementations are distributed and installed at various points of presence. DMA does specify how a DMA Service Object is registered and publishes its existence at a point of presence and how a DMA Service Object delivers a requested COM interface.
The DMA System Manager and System objects support the IdmaServiceRegistry interface. This interface has methods for registering and publishing service elements. A single program module may provide the implementation for multiple Service Objects each of which are described by a distinct service element.
When registered, each service element is given a distinct RegistrationID which can later be used to retrieve, publish, unpublish or remove the service element information. The DMA Service Registry maintains the following information for each service element:
Registering a service element makes that service element registry information available at the point of presence where the service element was registered (the point of service). Publishing the service element makes the service element registry information available at all points of presence which can reach the point of service.
Activation of a DMA service object requires that the service object’s module be loaded and that a function in that module be invoked, returning the desired object. These steps will vary according to the type of module in which the service object is implemented. DMA System Manager and System objects must provide the implementation of this activation logic.
For the Win32 DLL module type, the DLL referenced by the ModuleLocation parameter will export the DMA_GetServiceObject function as described below. It is likely that on other platforms a similar mechanism (e.g. using shared libraries) will be defined and that these will employ an entry point with the same general signature. Other module types and activation mechanisms may also be defined, for Win32 as well as for other platforms.
The general signature for the DMA_GetServiceObject function is as follows:
DmaRC DMA_GetServiceObject ( pDmaVoid pvEnvInfo, pDmaOpaqueString pProfile, Dmapv pIMalloc, Dmapv punkParent, DmaInteger32 lCharSetEncodingID, pDmaString pLocaleName, pDmaId pServiceObjectTypeID, pDmaId pServiceObjectID, DMA_REFIID riid, Dmappv ppIServiceObject );
This function is invoked using Profile, CharSetEncodingID, ServiceObjectTypeID, and ServiceObjectID parameter values extracted from a Service Registry. The values for the other parameters are generally derived from parameters specified on the dmaConnectSystemManager function and the IdmaSystemManager::ConnectSystem and IdmaSystem::ConnectDocSpace methods as appropriate.
A successful DMA_GetServiceObject call returns the COM interface specified by the riid parameter on a service object instance.
The System Object View: Integrating Systems for Access
Installing a System Object at the point of access
The installation of a DMA System service object is performed by a DMA application program operating with a connection to a DMA System Manager. The installation application registers and publishes the System service object using the DMA System Manager’s IdmaServiceRegistry interface, after which time, clients of that DMA System Manager may connect to the newly installed System using the IdmaSystemManager::ConnectSystem or IdmaSystemManager::EnumerateSystems methods.
Typical Connection Entry into the System Service Object Implementation Program
System Service Object implementations are required to honor DMA_GetServiceObject requests for the IdmaSystem interface. The IdmaSystemManager::ConnectSystem method simply activates the System service object and calls its DMA_GetServiceObject function passing downward it’s riid input parameter.
The DocSpace Object View: Integrating DocSpace Objects into Systems
Installing a DocSpace Service Object at a Point of Service
The installation of a DMA DocSpace service object is performed by a DMA application program operating with a connection to a DMA System. The installation application registers and publishes the DocSpace service object using the DMA System’s IdmaServiceRegistry interface, after which time, clients of that DMA System may connect to the newly installed DocSpace using the IdmaSystem::ConnectDocSpace or IdmaSystem::EnumerateDocSpaces methods.
Typical Connection Entry into the DocSpace Service Object Implementation Program
DocSpace Service Object implementations are required to honor DMA_GetServiceObject requests for the IdmaDocSpace interface. The IdmaSystem::ConnectDocSpace method simply activates the DocSpace service object and calls its DMA_GetServiceObject function passing downward it’s riid input parameter.
The Text Ordering Object View: Integrating Text Ordering Objects for Access
Installing a Text Ordering Service Object at a Point of Service
The installation of a DMA Text Ordering service object is performed by a DMA application program operating with a connection to a DMA System Manager. The installation application registers the Text Ordering service object using the DMA System’s IdmaServiceRegistry interface. Text Ordering Service Objects are not directly accessible by client applications. They are typically utilized by System Service Objects which utilize their parent object’s (System Manager) registry to locate a text ordering service element offering a needed text ordering.
Typical Connection Entry into the Text Ordering Service Object Implementation Program
Text Ordering Service Object implementations are required to honor DMA_GetServiceObject requests for the IdmaTextOrdering interface.
The Scope Factory Object View: Integrating a Scope Factory Object for Access
Installing a Scope Factory Service Object at a Point of Service
The installation of a DMA Scope Factory service object is performed by a DMA application program operating with a connection to a DMA System. The installation application registers the Scope Factory service object using the DMA System’s IdmaServiceRegistry interface. Scope Factory Service Objects are not directly accessible by client applications. They are accessed indirectly through the IdmaScopeFactory interface of the System object through which they are registered.
Typical Connection Entry into the Scope Factory Service Object Implementation Program
Scope Factory Service Object implementations are required to honor DMA_GetServiceObject requests for the IdmaScopeFactory interface.
The OIID Parser Object View: Integrating OIID Parser Objects for Access
Installing a OIID Parser Service Object at a Point of Service
The installation of a DMA OIID Parser service object is performed by a DMA application program operating with a connection to a DMA System Manager. The installation application registers the OIID Parser service object using the DMA System’s IdmaServiceRegistry interface. OIID Parser Service Objects are not directly accessible by client applications. They are accessed indirectly through the IdmaOIID interface of the System Manager object with which they are registered.
Typical Connection Entry into the OIID Parser Service Object Implementation Program
OIID Parser Service Object implementations are required to honor DMA_GetServiceObject requests for the IdmaOIID interface.