Network Working Group Nat Brown
INTERNET-DRAFT Charlie Kindel
<draft-brown-dcom-v1-spec-03.txt> Microsoft Corporation
Expires in six months January, 1998
Distributed Component Object Model Protocol -- DCOM/1.0
Status of this Memo
This document is an Internet-Draft. Internet-Drafts are working documents of
the Internet Engineering Task Force (IETF), its areas, and its working
groups. Note that other groups may also distribute working documents as
Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six months and
may
be updated, replaced, or obsoleted by other documents at any time. It is
inappropriate to use Internet-Drafts as reference material or to cite them
other than as "work in progress."
To learn the current status of any Internet-Draft, please check the "1id-
abstracts.txt" listing contained in the internet-drafts Shadow Directories
at
<ftp://ftp.is.co.za/internet-drafts> (Africa),
<ftp://nic.nordu.net/internet-
drafts> (Europe), <ftp://munnari.oz.au/internet-drafts> (Pacific Rim),
<ftp://ds.internic.net/internet-drafts> (US East Coast), or
<ftp://ftp.isi.edu/internet-drafts> (US West Coast).
Distribution of this document is unlimited. Please send comments to the
authors at <mailto:oleidea@microsoft.com>. General discussions about DCOM
and
its applications should take place on the DCOM mailing list. To subscribe,
send a piece of mail to <mailto:DCOM@listserv.msn.com>. Leave the subject
blank and in the body of the message, first type "subscribe" for non-digest
or "digest" for digest version, followed by "DCOM", and finally by your
name.
(example: "subscribe DCOM John Doe").
Abstract
The Distributed Component Object Model protocol is an application-level
protocol for object-oriented remote procedure calls useful for distributed,
component-based systems of all types. It is a generic protocol layered on
the
distributed computing environment (DCE) RPC specification and facilitates
the
construction of task-specific communication protocols through features such
as: a platform neutral argument/parameter marshaling format (NDR), the
Brown/Kindel page
1
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
ability for objects to support multiple interfaces with a safe, interface-
level versioning scheme suited to independent evolution by multiple parties,
the ability to make authenticated connections and to choose levels of
channel
security, and a transport-neutral data representation for references
(including by-value) to objects.
Brown/Kindel page 2
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
Table of Contents
Status of this Memo...................................1
Abstract..............................................1
Table of Contents.....................................3
1. Introduction.......................................5
1.1 Purpose......................................5
2. Overall Operation..................................6
2.1 Object Calls.................................6
2.2 OXIDs and Object Exporters...................7
2.3 Class Activation.............................8
2.4 Marshaled Interface References...............9
2.5 Reference Counting..........................10
2.6 Pinging.....................................10
2.7 QueryInterface..............................13
2.8 Causality ID................................13
3. Data Types and Structures.........................13
3.1 DCE Packet Headers..........................14
3.2 ORPC Base Definitions.......................14
3.3 OBJREF......................................20
3.4 STDOBJREF...................................22
3.5 SORFLAGS....................................23
3.6 ORPCINFOFLAGS...............................23
3.7 ORPCTHIS....................................24
3.8 ORPCTHAT....................................26
3.9 HRESULTs....................................26
3.10 Body Extensions............................27
4. IRemUnknown and IRemUnknown2 interfaces...........28
4.1 IRemUnknown::RemQueryInterface..............30
4.2 IRemUnknown2::RemQueryInterface2............31
4.3 IRemUnknown::RemAddRef......................32
4.4 IRemUnknown::RemRelease.....................34
5. The OXID Resolver.................................35
5.1 OXID Resolver Ports/Endpoints...............35
5.2 The IOXIDResolver Interface.................36
6. Object Activation.................................46
6.1 IRemoteActivation Ports/Endpoints...........46
Brown/Kindel page 3
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
6.2 The IRemoteActivation Interface.............47
7. Security Considerations...........................50
8. Acknowledgements..................................50
9. References........................................50
10. Author's Addresses...............................51
Brown/Kindel page 4
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
1. Introduction
The Distributed Component Object Model protocol (DCOM) is an application-
level protocol for object-oriented remote procedure calls and is thus also
called "Object RPC" or ORPC. The protocol consists of a set of extensions,
layered on the distributed computing environment (DCE) RPC specification
[CAE
RPC], with which familiarity is assumed. Familiarity is also assumed with
the
COM (Component Object Model) specification [COM].
Object RPC specifies:
@ How calls are made on an object
@ How object references are represented, communicated, and maintained
1.1 Purpose
There is a natural tendency in a networked environment to create entirely
new
application-level protocols as each new or seemingly unique combination of
client, user agent, and server requirement arises.
While in many situations the definition of a new protocol is useful and
justifiable, there are numerous features which have eventually been added to
or required from each new protocol (or which become layered above them) as
they evolve and become used in broader contexts.
A design goal of the DCOM protocol is the inherent support of standard
features required by any distributed application communication protocol. In
other words, to act as a framework to facilitate the construction of task-
specific communication paths between distributed applications.
Data Marshaling
A common occurrence among user agents using the HTTP protocol today is the
use of complex, task-specific Query URL syntax and HTTP POSTs. Also
increasingly common is the POSTing and response with custom MIME types to
and
from resources which interpret the format and reply in same. While workable,
there are drawbacks to this approach including increased complexity and work
to produce and consume each new (and unique) format in the client and
server,
lessened ability to build task-specific firewalls for administration and
security purposes, and in many cases definition of platform-centric formats.
DCOM utilizes the Network Data Representation (NDR) for arbitrary data types
supported by DCE RPC.
Security
Brown/Kindel page 5
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
DCOM leverages the authentication, authorization, and message integrity
capabilities of DCE RPC. An implementation may support any level of DCE RPC
security. Any connection or call can be made as secure or as insecure as
negotiated by the client and the server.
Safe Non-Coordinated Versioning of Interfaces
In DCOM versioning of interfaces is done through identifiers which are
universally unique (UUID's). To version a published interface, a new
interface is defined with a different UUID to the updated specification.
Multiple parties can simultaneously introduce "revisions" to interfaces by
defining related but distinct interfaces without fear of colliding with each
other's version numbers and without fear of breaking each other's down-level
or up-level clients.
To date, the bulk of task-specific protocols (such as custom POSTs or MIME
types using HTTP) have little or no concept of versioning at all, and simply
"narrow" the incompatibility window by updating clients (typically pages
which are being downloaded anyway) and servers (CGI scripts or other HTTP
server infrastructure) simultaneously.
2. Overall Operation
The Object RPC protocol highly leverages the OSF DCE RPC network protocol
(see the reference [CAE RPC]). This leverage occurs at both the
specification
level and the implementation level: the bulk of the implementation effort
involved in implementing the DCOM network protocol is in fact that of
implementing the DCE RPC network protocol on which it is built.
2.1 Object Calls
An actual COM network remote procedure call (hereinafter referred to as "an
ORPC") is in fact a true DCE remote procedure call (herein termed "a DCE
RPC"), a "Request PDU" conforming to the specification for such calls per
[CAE RPC].
In an ORPC, the object ID field of the invocation header as specified in
[CAE
RPC] contains an "IPID". An IPID is a 128-bit identifier known as an
interface pointer identifier which represents a particular interface on a
particular object in a particular server. As it is passed in the object ID
fields of a DCE RPC, the static type of an IPID is in fact a UUID. However,
IPIDs are scoped not globally but rather only relative to the server
process
Brown/Kindel page 6
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
which originally allocated them; IPIDs do not necessarily use the standard
UUID allocation algorithm, but rather may use a machine-specific algorithm
which can assist with dispatching.
In an ORPC, the interface ID field of the RPC header specifies the IID, and
arguments are found in the body, as usual. However, when viewed from the DCE
RPC perspective an additional first argument is always present that is
absent
in the corresponding COM interface specification. This argument is of type
ORPCTHIS, which is described in Section 3.7. It is placed first in the body
of the Request PDU, before the actual arguments of the ORPC.
It is specifically legal for an ORPC to attempt a call a method number on a
given interface which is beyond the number of methods believed by the server
to be in that interface. Such calls should cause a fault.
Similarly, in a reply to an ORPC (a DCE RPC "Response PDU"), when viewed
from
the DCE RPC perspective, an additional first return value is always present
that is absent in the corresponding COM interface specification. This
argument is of type ORPCTHAT, which is described in Section 3.8. It is
placed
first in the body of the Response PDU, before the actual return values of
the
ORPC.
An ORPCTHAT may also be present in a "Fault PDU." In the Connectionless (CL)
Fault PDU, it is placed four bytes after the 32- bit fault code which
normally comprises the entire body of the PDU, thus achieving eight byte
alignment for the ORPCTHAT; the intervening padding bytes are presently
reserved and must be zero. The PDU body length is of course set to encompass
the entire body of the Fault PDU, including the ORPCTHAT. In the Connection-
Oriented (CO) Fault PDU, the ORPCTHAT is placed in the standard location
allocated for the "stub data." In a Fault PDU of either form that results
from an ORPC, if an ORPCTHAT is not present then no other data may be
substituted in its here-specified location in the PDU.
2.2 OXIDs and Object Exporters
Although an IPID from a logical perspective semantically determines the
server, object and interface to which a particular call should be directed,
it does not by itself indicate the binding information necessary to actually
carry out an invocation.
The protocol represents this "how-to" communication information in a 64-bit
value called an object exporter identifier, otherwise known as an OXID.
Conceptually, an OXID can be thought of as an implementation scope for an
object, which may be a whole machine, a given process, a thread within that
process, or other more esoteric implementation scope, but the exact
definition of such scopes has no bearing on the protocol itself. Data
Brown/Kindel page 7
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
structures in each Object Exporter keep track of the IPIDs exported and
imported by that Object Exporter.
A given machine at any moment may support several OXIDs; however there is
always a unique OXID Resolver service per machine which coordinates the
management of all the OXIDs on the machine. The OXID Resolver typically (but
not necessarily) resides at well-known ports (or endpoints, depending on
your
terminology -- one per protocol, of course) on the machine. It supports a
DCE
RPC interface known as IOXIDResolver, described in Section 5.2.
An OXID is used to determine the RPC string bindings that allow calls to
reach their target IPID. Before making a call, the calling process must
translate an OXID into a set of bindings that the underlying RPC
implementation understands. It accomplishes this by maintaining a cache of
these mappings. When the destination application receives an object
reference, it checks to see if it recognizes the OXID. If it does not, then
it asks the OXID Resolver which scopes the OXID specified in the object
reference for the translation, and saves the resulting set of string
bindings in a local table that maps OXIDs to string bindings.
Associated with each OXID (ie each Object Exporter) is COM object termed an
"OXID object." OXID objects implement (at least) the IRemUnknown interface,
a
COM interface through which remote management of reference counts and
requests for interfaces are returned.
2.3 Class Activation
The server-provided DCOM class activation facility provides a way for a
client to instantiate a new class object on a host machine, obtain its OXID,
and obtain one or more IPIDs for the interfaces that it is interested in
communicating through, all in one network round-trip. While it is primarily
intended for the creation of new objects, the activation facility is free to
return the same OXID and IPIDs for all activation requests of a particular
class of object; this gives clients an easy way to access a well-known
service without having to have a priori knowledge of a specific object (i.e.
OXID & IPID) on the host, knowledge which can be invalidated by a reboot or
a
network failure.
Clients are expected to know beforehand either the CLSID or a file moniker
which will result in the creation of the class object that they are
interested in communicating with. Clients also have the option of providing
a
client-side IStorage object which will be used to instantiate and initialize
the server-side object.
Brown/Kindel page 8
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
2.4 Marshaled Interface References
The DCOM protocol extends the Network Data Representation (NDR) standard
specified in [CAE RPC] by defining what can be thought of as a new primitive
data type that can be marshaled: that of an interface reference to an
object.
This is the only extension to NDR made by the DCOM protocol.
A marshaled interface reference is described by a type known as an OBJREF,
which is described in detail in Section 3.3. An OBJREF in actuality has
several variations:
NULL
This is a reference to no object.
STANDARD
A standard remote reference. Known as a STDOBJREF. A STDOBJREF contains:
@ An IPID, which uniquely specifies the interface and object.
@ An object ID (OID), which uniquely specifies the identity of the object on
which the IPID is found (scoped to the object exporter with which the
object is associated).
@ An OXID, which identifies the scope where the implementation of the object
is active, and can be used to reach the interface pointer.
@ A reference count, indicating the number of references to this IPID that
are conveyed by this marshaling. This count, though typically a value of
one, may in fact be zero, one, or more (see the next section).
@ Some flags, explained later.
CUSTOM
Contains a class ID (CLSID) and class-specific information.
The Custom format gives an object control over the representation of
references to itself. For example, an immutable object might be passed by
value, in which case the class-specific information would contain the
object's immutable data.
HANDLER
A sub-case of the custom reference in which the class- specific information
is standardized.
Brown/Kindel page 9
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
For example, an object wishes to be represented in client address spaces by
a
proxy object that caches state. In this case, the class-specific information
is just a standard reference to an interface pointer that the handler (proxy
object) will use to communicate with the original object.
Interface references are always marshaled in little-endian byte order,
irrespective of the byte order prevailing in the remainder of the data being
marshaled.
2.5 Reference Counting
In the DCOM protocol, remote reference counting is conducted per interface
(per IPID).
The actual increment and decrement calls are carried out using
(respectively)
the RemAddRef and RemRelease methods in a COM interface known as IRemUnknown
found on the OXID object associated with each OXID, the IPID of which is
returned from the function IOXIDResolver::ResolveOxid (section 5.2.1) or
IRemoteActivation::RemoteActivation (section 6.2.1). In contrast to their
analogues in IUnknown, RemAddRef and RemRelease can in one call increment or
decrement the reference count of many different IPIDs by an arbitrary
amount;
this allows for greater network efficiency. In the interests of performance,
client COM implementations typically do not immediately translate each local
AddRef and Release into a remote RemAddRef and RemRelease. Rather, the
actual
remote release of all interfaces on an object is typically deferred until
all
local references to all interfaces on that object have been released.
Further, one actual remote reference count may be used to service many local
reference counts; that is, the client infrastructure may multiplex zero or
more local references to an interface into zero or one remote references on
the actual IPID.
To prevent a malicious application from calling RemRelease incorrectly, an
application may request secure references. In that case the application
must
call RemAddRef (and RemRelease later on) securely and must request private
references. Private references are stored by client identity so one client
cannot release another client’s references. DCOM requires that each client
make a call to get his own secure references, rather then receiving a secure
reference from someone who already has one. This reduces the efficiency of
interface marshalling because the client must make a callback.
2.6 Pinging
The above reference counting scheme would be entirely adequate on its own if
clients never terminated abnormally, but in fact they do, and the system
Brown/Kindel page
10
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
needs to be robust in the face of clients terminating abnormally when they
hold remote references. In a DCE RPC, one typically addresses this issue
through the use of context handles. Context handles are not used, however,
by
the DCOM protocol, for reasons of expense. The basic underlying technology
used in virtually all protocols for detecting remote abnormal termination is
that of periodic pings. Naive use of RPC context handles would result in per
object per client process pings being sent to the server. The DCOM protocol
includes a pinging infrastructure to significantly reduce network traffic by
relying on the client OXID Resolver implementation to do local management of
client liveness detection, and having the actual pings be sent only on a
machine by machine basis.
Pinging is carried out on a per-object (per OID), not a per- interface (per-
IPID) basis. Architecturally, at its server machine, each exported object
(each exported OID) has associated with it a pingPeriod time value and a
numPingsToTimeOut count which together (through their product) determine the
overall amount of time known as the "ping period" that must elapse without
receiving a ping on that OID before all the remote references to IPIDs
associated with that OID can be considered to have expired. Once expiration
has occurred, the interfaces behind the IPIDs can, as would be expected, be
reclaimed solely on the basis of local knowledge, though the timeliness with
which this is carried out, if at all, is implementation specific detail of
the server. If the server COM infrastructure defers such garbage collection
in this situation (perhaps because it has local references keeping the
interface pointer alive) and it later hears a ping, then it knows a network
partition healed. It can consider the extant remote references to be
reactivated and can continue remote operations.
When interface pointers are conveyed from one client to another, such as
being passed as either [in] or [out] parameters to a call, the interface
pointer is marshaled in one client and unmarshaled in the other. In order to
successfully unmarshal the interface, the destination client must obtain at
least one reference count on the interface. This is usually accomplished by
passing in the marshaled interface STDOBJREF a cPublicRefs of (at least)
one;
the destination client then takes ownership of that many (more) reference
counts to the indicated IPID, and the source client then owns that many
fewer
reference counts on the IPID. It is legal, however, for zero reference
counts
to be passed in the STDOBJREF; here, the destination client must (if it does
not already have access to that IPID and thus have a non-zero reference
count
for it) before it successfully unmarshals the interface reference
(concretely, e.g., before CoUnmarshalInterface returns) call to the object
exporter using IRemUnknown::RemAddRef to obtain a reference count for it. If
the destination client is in fact the object's server, then special
Brown/Kindel page
11
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
processing is required by the destination client. The remote reference
counts
being passed to it should, in effect, be "taken out of circulation," as what
where heretofore remote references are being converted into local
references.
Thus, the reference counts present in the STDOBJREF are in fact decremented
from the remote reference count for the IPID in question.
Some objects have a usage model such that they do not need to be pinged at
all; such objects are indicated by the presence of a flag in a STDOBJREF to
an interface on the object. Objects which are not pinged in fact need not be
reference counted either, though it is legal (but pointless) for a client to
reference count the IPIDs of such objects.
For all other objects, assuming a non-zero ping period, it is the
responsibility of the holder of an interface reference on some object to
ensure that pings reach the server frequently enough to prevent expiration
of
the object. The frequency used by a client depends on the ping period, the
reliability of the channel between the client and the server, and the
probability of failure (no pings getting through and possible premature
garbage-collection) that the client is willing to tolerate. The ping packet
and / or its reply may both request changes to the ping period. Through this
mechanism, network traffic may be reduced in the face of slow links to busy
servers.
2.6.1 Delta Pinging
Without any further refinements, ping messages could be quite hefty. If
machine A held 1024 remote object references (OIDs) on machine B, then it
would send 16K byte ping messages. This would be annoying if the set of
remote objects was relatively stable and the ping messages were the same
from
ping to ping.
The delta mechanism reduces the size of ping messages. It uses a ping-set
interface that allows the pinging of a single set to replace the pinging of
multiple OIDs.
Instead of pinging each OID, the client defines a set. Each ping contains
only the set id and the list of additions and subtractions to the set.
Objects that come and go within one ping period are removed from the set
without ever having been added.
The pinging protocol is carried out using two methods in the (DCE RPC)
interface IOXIDResolver on the OXID Resolver: ComplexPing, and SimplePing.
ComplexPing is used by clients to group the set of OIDs that they must ping
into sets known to the server. These entire sets of OIDs can then be
subsequently pinged with a single, short, call to SimplePing.
Brown/Kindel page
12
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
2.7 QueryInterface
zThe IRemUnknown interface on the OXID object, in addition to servicing
reference counting as described above also services QueryInterface calls for
remote clients for IPIDs managed by that object exporter.
IRemUnknown::RemQueryInterface differs from IUnknown::QueryInterface in much
the same way as RemAddRef and RemRelease differ from AddRef and Release, in
that it is optimized for network access by being able to retrieve many
interfaces at once.
2.8 Causality ID
Each ORPC carries with it a UUID known as the causality id that connects
together the chain of ORPC calls that are causally related. If an outgoing
ORPC is made while servicing an incoming ORPC, the outgoing call is to have
the same causality id as the incoming call. If an outgoing ORPC is made
while
not servicing an incoming ORPC, then a new causality id is allocated for it.
Causality ids may in theory be reused as soon as it is certain that no
transitively outstanding call is still in progress which uses that call. In
practice, however, in the face of transitive calls and the possibility of
network failures in the middle of such call chains, it is difficult to know
for certain when this occurs. Thus, pragmatically, causality ids are not
reusable.
The causality id can be used by servers to understand when blocking or
deferring an incoming call (supported in some COM server programming models)
is very highly probable to cause a deadlock, and thus should be avoided.
The causality id for maybe, idempotent, and broadcast calls must be set to
null (e.g., all zeros). If a server makes a ORPC call while processing such
a
call, a new causality id must be generated as if it were a top level call.
3. Data Types and Structures
This following several sections present the technical details of the DCOM
protocol.
Brown/Kindel page
13
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
3.1 DCE Packet Headers
Object RPC sits entirely on top of DCE RPC. The following list describes the
elements of ORPC that are specified above and beyond DCE RPC.
@ The object id field of the header must contain the IPID.
@ The interface id of the RPC header must contain the IID, even though it is
not needed given the IPID. This allows ORPC to sit on top of DCE RPC. An
unmodified DCE RPC implementation will correctly dispatch based on IID and
IPID. An optimized RPC need only dispatch based on IPID.
@ An IPID uniquely identifies a particular interface on a particular object
on a machine. The converse is not true; a particular interface on a
particular object may be represented by multiple IPIDs. IPIDs are unique
on
their OXID. IPIDs may be reused, however reuse of IPIDs should be avoided.
@ Datagram, maybe, and idempotent calls are all allowed in ORPC.
@ Interface pointers may not be passed on maybe or idempotent calls.
@ Datagram broadcasts are not allowed in ORPC.
@ Faults are returned in the stub fault field of the DCE RPC fault packet.
Any 32 bit value may be returned. Only RPC_E_VERSION_MISMATCH is pre-
specified.
@ DCE RPC cancel is supported.
@ All interface version numbers must be 0.0.
@ The transfer syntax GUID is {8a885d04-1ceb-11c9-9fe8-08002b104860},
version
2 (0x02).
3.2 ORPC Base Definitions
There are several fundamental data types and structures on which the COM
network protocol is built. These types are shown here in standard C header
format.
[
uuid(99fcfe60-5260-101b-bbcb-00aa0021347a),
pointer_default(unique)
]
Brown/Kindel page
14
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
interface ObjectRpcBaseTypes
{
////////////////////////////////////////////////////////////
//
// Identifier Definitions
//
////////////////////////////////////////////////////////////
typedef unsigned hyper ID;
typedef ID MID; // Machine Identifier
typedef ID OXID; // Object Exporter Identifier
typedef ID OID; // Object Identifer
typedef ID SETID; // Ping Set Identifier
typedef GUID IPID; // Interface Pointer Identifier
typedef GUID CID; // Causality Identifier
typedef const IPID &REFIPID;
typedef REFGUID REFIPID;
//////////////////////////////////////////////////////////////////
//
// ORPC Call Packet Format
//
//////////////////////////////////////////////////////////////////
// COM_MINOR_VERSION = 1 (NT4.0, SP1, SP2, DCOM95).
// - Initial Release
// - Must be used when talking to downlevel machines, including
// on Remote Activation calls.
// COM_MINOR_VERSION = 2 (NT4.0 SP3 and beyond).
// - Added ResolveOxid2 to IObjectExporter to retrieve the
// COM version number of the server. Passed to the NDR engine
// to fix fatal endian-ness flaw in the way OLEAUTOMATION
marshals
// BSTRS. Previous way used trailing padding, which is not NDR
// compatible. See Bug# 69189.
// COM_MINOR_VERSION = 3 (NT4.0 SP4 and DCOM95 builds 1018 and beyond)
// - OLEAUT32 added two new types to the SAFEARRAY, but SAFEARRAY
// previously included the "default" keyword, which prevented
// downlevel NDR engines from correctly handling any extensions.
// Machines with version >=5.3 don't use "default" and will
// gracefully handle future extensions to SAFEARRAY.
// old constants (for convenience)
const unsigned short COM_MINOR_VERSION_1 = 1;
const unsigned short COM_MINOR_VERSION_2 = 2;
Brown/Kindel page
15
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
// current version
const unsigned short COM_MAJOR_VERSION = 5;
const unsigned short COM_MINOR_VERSION = 3;
// Component Object Model version number
typedef struct tagCOMVERSION
{
unsigned short MajorVersion; // Major version number
unsigned short MinorVersion; // Minor version number
} COMVERSION;
// enumeration of additional information present in the call packet.
// Should be an enum but DCE IDL does not support sparse enumerators.
const unsigned long ORPCF_NULL = 0; // no additional info in
packet
const unsigned long ORPCF_LOCAL = 1; // call is local to this
machine
const unsigned long ORPCF_RESERVED1 = 2; // reserved for local use
const unsigned long ORPCF_RESERVED2 = 4; // reserved for local use
const unsigned long ORPCF_RESERVED3 = 8; // reserved for local use
const unsigned long ORPCF_RESERVED4 = 16; // reserved for local use
// Extension to implicit parameters.
typedef struct tagORPC_EXTENT
{
GUID id; // Extension identifier.
unsigned long size; // Extension size.
[size_is((size+7)&~7)] byte data[]; // Extension data.
} ORPC_EXTENT;
// Array of extensions.
typedef struct tagORPC_EXTENT_ARRAY
{
unsigned long size; // Num extents.
unsigned long reserved; // Must be zero.
[size_is((size+1)&~1,), unique] ORPC_EXTENT **extent; // extents
} ORPC_EXTENT_ARRAY;
// implicit 'this' pointer which is the first [in] parameter on
Brown/Kindel page
16
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
// every ORPC call.
typedef struct tagORPCTHIS
{
COMVERSION version; // COM version number
unsigned long flags; // ORPCF flags for presence of other
data
unsigned long reserved1; // set to zero
CID cid; // causality id of caller
// Extensions.
[unique] ORPC_EXTENT_ARRAY *extensions;
} ORPCTHIS;
// implicit 'that' pointer which is the first [out] parameter on
// every ORPC call.
typedef struct tagORPCTHAT
{
unsigned long flags; // ORPCF flags for presence of other
data
// Extensions.
[unique] ORPC_EXTENT_ARRAY *extensions;
} ORPCTHAT;
//////////////////////////////////////////////////////////////////
//
// Marshaled COM Interface Wire Format
//
//////////////////////////////////////////////////////////////////
// DUALSTRINGARRAYS are the return type for arrays of network addresses,
// arrays of endpoints and arrays of both used in many ORPC interfaces
const unsigned short NCADG_IP_UDP = 0x08;
const unsigned short NCACN_IP_TCP = 0x07;
const unsigned short NCADG_IPX = 0x0E;
const unsigned short NCACN_SPX = 0x0C;
const unsigned short NCACN_NB_NB = 0x12;
const unsigned short NCACN_NB_IPX = 0x0D;
const unsigned short NCACN_DNET_NSP = 0x04;
const unsigned short NCACN_HTTP = 0xlF;
Brown/Kindel page
17
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
typedef struct tagSTRINGBINDING
{
unsigned short wTowerId; // Cannot be zero.
unsigned short aNetworkAddr; // Zero terminated.
} STRINGBINDING;
const unsigned short COM_C_AUTHZ_NONE = 0xffff;
typedef struct tagSECURITYBINDING
{
unsigned short wAuthnSvc; // Cannot be zero.
unsigned short wAuthzSvc; // Must not be zero.
unsigned short aPrincName; // Zero terminated.
} SECURITYBINDING;
typedef struct tagDUALSTRINGARRAY
{
unsigned short wNumEntries; // Number of entries in array.
unsigned short wSecurityOffset; // Offset of security info.
// The array contains two parts, a set of STRINGBINDINGs
// and a set of SECURITYBINDINGs. Each set is terminated by an
// extra zero. The shortest array contains four zeros.
[size_is(wNumEntries)] unsigned short aStringArray[];
} DUALSTRINGARRAY;
// signature value for OBJREF (object reference, actually the
// marshaled form of a COM interface).
const unsigned long OBJREF_SIGNATURE = 0x574f454d; // 'MEOW'
// flag values for OBJREF
const unsigned long OBJREF_STANDARD = 0x1; // standard marshaled objref
const unsigned long OBJREF_HANDLER = 0x2; // handler marshaled objref
const unsigned long OBJREF_CUSTOM = 0x4; // custom marshaled objref
// Flag values for a STDOBJREF (standard part of an OBJREF).
// SORF_OXRES1 - SORF_OXRES8 are reserved for the object exporters
// use only, object importers must ignore them and must not enforce MBZ.
const unsigned long SORF_OXRES1 = 0x1; // reserved for exporter
const unsigned long SORF_OXRES2 = 0x20; // reserved for exporter
Brown/Kindel page
18
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
const unsigned long SORF_OXRES3 = 0x40; // reserved for exporter
const unsigned long SORF_OXRES4 = 0x80; // reserved for exporter
const unsigned long SORF_OXRES5 = 0x100;// reserved for exporter
const unsigned long SORF_OXRES6 = 0x200;// reserved for exporter
const unsigned long SORF_OXRES7 = 0x400;// reserved for exporter
const unsigned long SORF_OXRES8 = 0x800;// reserved for exporter
const unsigned long SORF_NULL = 0x0; // convenient for
initializing SORF
const unsigned long SORF_NOPING = 0x1000;// Pinging is not required
// standard object reference
typedef struct tagSTDOBJREF
{
unsigned long flags; // STDOBJREF flags (see above)
unsigned long cPublicRefs; // count of references passed
OXID oxid; // oxid of server with this oid
OID oid; // oid of object with this ipid
IPID ipid; // ipid of Interface
} STDOBJREF;
// OBJREF is the format of a marshaled interface pointer.
typedef struct tagOBJREF
{
unsigned long signature; // must be OBJREF_SIGNATURE
unsigned long flags; // OBJREF flags (see above)
GUID iid; // interface identifier
[switch_is(flags), switch_type(unsigned long)] union
{
[case(OBJREF_STANDARD)] struct
{
STDOBJREF std; // standard objref
DUALSTRINGARRAY saResAddr; // resolver address
} u_standard;
[case(OBJREF_HANDLER)] struct
{
STDOBJREF std; // standard objref
CLSID clsid; // Clsid of handler code
DUALSTRINGARRAY saResAddr; // resolver address
Brown/Kindel page
19
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
} u_handler;
[case(OBJREF_CUSTOM)] struct
{
CLSID clsid; // Clsid of unmarshaling code
unsigned long cbExtension;// size of extension data
unsigned long size; // size of data that follows
[size_is(size), ref] byte *pData; // extension + class
specific data
} u_custom;
} u_objref;
} OBJREF;
// wire representation of a marshalled interface pointer
typedef struct tagMInterfacePointer
{
ULONG ulCntData; // size of data
[size_is(ulCntData)] BYTE abData[]; // data (OBJREF)
} MInterfacePointer;
typedef [unique] MInterfacePointer * PMInterfacePointer;
}
//////////////////////////////////////////////////////////////////
3.3 OBJREF
An OBJREF is the data type used to represent an actual marshaled object
reference. An OBJREF can either be empty or assume one of three variations,
depending on the degree to which the object being marshaled uses the hook
architecture (IMarshal, etc.) in the marshaling infrastructure. The OBJREF
structure is a union consisting of a switch flag followed by the appropriate
data.
3.3.1 OBJREF_STANDARD
Contains one interface of an object marshaled in standard form. Contains a
standard reference, along with a set of protocol sequences and network
Brown/Kindel page
20
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
addresses that can be used to bind to an OXID resolver that is able to
resolve the OXID in the STDOBJREF. This is useful when marshaling a proxy to
give to another machine (a.k.a. the "middleman" case). The marshaling
machine
specifies the saResAddr for the OXID Resolver on the server machine,
eliminating the need for the unmarshaler to call the marshaler (middleman)
back to get this information. Further, the marshaler does not need to keep
the OXID in its cache beyond the lifetime of its own references in order to
satisfy requests from parties that it just gave the OBJREF to.
Member Type Semantic
signature unsigned long Must be OBJREF_SIGNATURE
flags unsigned long OBJREF flags (section 3.5)
iid GUID Interface identifier
std STDOBJREF A standard object reference used to connect to
the source object (Section 3.4).
saResAddr STRINGARRAY The resolver address.
3.3.2 OBJREF_HANDLER
A marshaling of an object that wishes to use handler marshaling. For
example,
an object wishes to be represented in client address spaces by a proxy
object
that caches state. In this case, the class- specific information is just a
standard reference to an interface pointer that the handler (proxy object)
will use to communicate with the original object. See the IStdMarshalInfo
interface.
Member Type Semantic
signature unsigned long Must be OBJREF_SIGNATURE
flags unsigned long OBJREF flags (section 3.5)
iid GUID Interface identifier
std STDOBJREF A standard object reference used to connect to
the source object (Section 3.4).
clsid CLSID The CLSID of handler to create in the
destination client.
saResAddr STRINGARRAY The resolver address.
Brown/Kindel page
21
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
3.3.3 OBJREF_CUSTOM
A marshaling of an object which supports custom marshaling. The Custom
format
gives an object control over the representation of references to itself. For
example, an immutable object might be passed by value, in which case the
class-specific information would contain the object's immutable data. See
the
IMarshal interface.
Member Type Semantic
signature unsigned long Must be OBJREF_SIGNATURE
flags unsigned long OBJREF flags (section 3.5)
GUID iid Interface identifier
clsid CLSID The CLSID of the object to create in the
destination client.
cbExtension unsigned long The size of the extension data.
size unsigned long The size of the marshaled data provided by the
source object, plus the size of the extension
data, and passed in pData.
pData byte* The data bytes that should be passed to
IMarshal::UnmarshalInterface on a new instance
of class clsid in order to initialize it and
complete the unmarshal process (class specific
data).
The first cbExtension bytes are the reserved
for future extensions to the protocol, and
should not be passed into the custom
unmarshaler. CoUnmarshalInterface should skip
the extension data, and the data starting at
pData+cbExtension should be given to the custom
unmarshaler.
3.4 STDOBJREF
An instance of a STDOBJREF represents a COM interface pointer that has been
marshaled using the standard COM network protocol.
The members and semantics of the STDOBJREF structure are as follows:
Member Semantic
flags Flag values taken from the enumeration SORFFLAGS. These are
described in Section 3.5.
Brown/Kindel page
22
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
cPublicRefs The number of reference counts on ipid that are being
transferred in this marshaling.
oxid The OXID of the server that owns this OID.
oid The OID of the object to which ipid corresponds.
ipid The IPID of the interface being marshaled.
3.5 SORFLAGS
The various SORFLAGS values have the following meanings. The SORF_OXRESxxx
bit flags are reserved for the object exporter's use only, and must be
ignored by object importers. They need not be passed through when marshaling
an interface proxy.
Flag Meaning
SORF_NULL Convenient for initialization.
SORF_OXRES1 Reserved for exporter.
SORF_OXRES2 Reserved for exporter.
SORF_OXRES3 Reserved for exporter.
SORF_OXRES4 Reserved for exporter.
SORF_OXRES5 Reserved for exporter.
SORF_OXRES6 Reserved for exporter.
SORF_OXRES7 Reserved for exporter.
SORF_OXRES8 Reserved for exporter.
SORF_NOPING This OID does not require pinging. Further, all
interfaces on this OID, including this IPID, need not be
reference counted. Pinging and reference counting on
this object and its interfaces are still permitted,
however, though such action is pointless.
3.6 ORPCINFOFLAGS
The various ORPCINFOFLAGS have the following meanings.
Flag Meaning
ORPCF_NULL (Not a real flag. Merely a defined constant indicating the
absence of any flag values.)
ORPCF_LOCAL The destination of this call is on the same machine on
which
it originates. This value is never to be specified in calls
which are not in fact local.
Brown/Kindel page
23
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
ORPCF_RESERVED1 If ORPCF_LOCAL is set, then reserved for local use;
otherwise, reserved for future use.
ORPCF_RESERVED2 If ORPCF_LOCAL is set, then reserved for local use;
otherwise, reserved for future use.
ORPCF_RESERVED3 If ORPCF_LOCAL is set, then reserved for local use;
otherwise, reserved for future use.
ORPCF_RESERVED4 If ORPCF_LOCAL is set, then reserved for local use;
otherwise, reserved for future use.
Implementations may use the local and reserved flags to indicate any extra
information needed for local calls. Note that if the ORPCF_LOCAL bit is not
set and any of the other bits are set then the receiver should return a
fault.
3.7 ORPCTHIS
In every Request PDU that is an ORPC, the body (CL case) or the stub data
(CO
case) which normally contains the marshaled arguments in fact begins with an
instance of the ORPCTHIS structure. The marshaled arguments of the COM
interface invocation follow the ORPCTHIS; thus, viewed at the DCE RPC
perspective, the call has an additional first argument. The ORPCTHIS is
padded with zero-bytes if necessary to achieve an overall size that is a
multiple of eight bytes; thus, the remaining arguments are as a whole eight
byte aligned.
As in regular calls, the causality id must be propagated. If A calls
ComputePi on B, B calls Release on C (which gets converted to RemRelease),
and C calls Add on A, A will see the same causality id that it called B
with.
Member Type Semantic
version COMVERSION The version number of the COM protocol used
to make this particular ORPC. The initial
value will be 5.1. Each packet contains the
sender's major and minor ORPC version
numbers. The client's and server's major
versions must be equal. Backward compatible
changes in the protocol are indicated by
higher minor version numbers. Therefore, a
server's minor version must be greater than
or equal to the client's. However, if the
server's minor version exceeds the client's
Brown/Kindel page
24
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
minor version, it must return the client's
minor version and restrict its use of the
protocol to the minor version specified by
the client. A protocol version mismatch
causes the RPC_E_VERSION_MISMATCH ORPC
fault
to be returned.
flags unsigned long Flag values taken from the enumeration
ORPCINFOFLAGS (section 3.6). Reserved
unsigned long Must be set to zero.
reserved1 unsigned long Set to zero.
cid CID The causality id of this ORPC.
extensions ORPC_EXTENT_ARRAY* The body extensions, if any, passed with
this call. Body extensions are GUID-tagged
blobs of data which are marshaled as an
array of bytes. Extensions are always
marshaled with initial eight byte
alignment.
Body extensions which are presently defined
are described in Section 3.10.
The cid field contains the causality id. Each time a client makes a unique
call, a new causality id is generated. If a server makes a call while
processing a request from a client, the new call must have the same
causality
id as the call currently being processed. This allows simple servers to
avoid
working on more then one thing at a time (for example A calls B calls A
again, meanwhile C tries to call A with a new causality id). It tells the
server that he is being called because he asked someone to do something for
him. There are several interesting exceptions.
The causality id for maybe and idempotent calls must be set to CID_NULL. If
a
server makes a ORPC call while processing such a call, a new causality id
must be generated.
In the face of network failures, the same causality id may end up in use by
two independent processes at the same time. If A calls B calls C calls D and
C fails, both B and D can independently, simultaneously make calls to E with
the same causality id.
The extensions field contains extensions to the channel header, described in
Section 3.10. Note that in order to force the ORPCTHIS header to be 8 byte
aligned an even number of extensions must be present and the size of the
extension data must be a multiple of 8.
Brown/Kindel page
25
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
3.8 ORPCTHAT
In every Response PDU that is an ORPC, the body (CL case) or the stub data
(CO case) which normally contains the marshaled output parameters in fact
begins with an instance of the ORPCTHAT structure. The marshaled output
parameters of the COM interface invocation follow the ORPCTHAT; thus, viewed
at the DCE RPC perspective, the call has an additional output parameters.
The
ORPCTHAT is padded with zero-bytes if necessary to achieve an overall size
that is a multiple of eight bytes; thus, the remaining output parameters as
a
whole are eight byte aligned.
Member Type Semantic
flags unsigned long Flag values taken from the enumeration
ORPCINFOFLAGS (section 3.6).
extensions ORPC_EXTENT_ARRAY* The body extensions, if any, returned by
this call. See Section 3.10 for a general
description of body extensions as well as
a description of existing well-known
extensions.
3.9 HRESULTs
HRESULTs are the 32-bit return value from ORPC methods. The following is a
partial list of already defined HRESULTs.
Value Meaning
S_OK Success. (0x00000000)
E_OUTOFMEMORY Insufficient memory to complete the call.
(0x80000002)
E_INVALIDARG One or more arguments are invalid. (0x80000003)
E_NOINTERFACE No such interface supported (0x80000004)
E_ACCESSDENIED A secured operation has failed due to inadequate
security privileges. (0x80070005)
E_UNEXPECTED Unknown, but relatively catastrophic error.
(0x8000FFFF)
S_FALSE False. (0x00000001)
RPC_S_PROCNUM_OUT_OF_RANGE The procedure number is out of range.
(0xC002002E)
RPC_E_INVALID_OXID The object exporter was not found. (0x80070776)
RPC_E_INVALID_OID The object specified was not found or
recognized.
Brown/Kindel page
26
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
(0x80070777)
RPC_E_INVALID_SET The object exporter set specified was not found.
(0x80070778)
RPC_E_INVALID_OBJECT The requested object does not exist.
(0x80010114)
RPC_E_VERSION_MISMATCH The version of COM on the client and server
machines does not match. (0x80010110)
Further details TBS.
3.10 Body Extensions
Body Extensions are UUID-tagged blocks of data which are useful for
conveying
additional, typically out-of-band, information on incoming invocations
(within ORPCTHIS, Section 3.7) and in replies (within ORPCTHAT, Section
3.8).
Any implementations of the DCOM protocol may define its own extensions with
their own UUIDs. Implementations should skip over extensions which they do
not recognize or do not wish to support.
Body Extensions are marshaled as an array of bytes with initial eight byte
alignment. The following sections describe several existing body extensions.
3.10.1 Debugging Extension
{f1f19680-4d2a-11ce-a66a-0020af6e72f4}
This extension aids in debugging ORPC. In particular it is designed to allow
single stepping over an ORPC call into the server and out of the server into
the client.
Further details TBS.
3.10.2 Extended Error Extension
{f1f19681-4d2a-11ce-a66a-0020af6e72f4}
The extended error information body extension conveys extended error
information concerning the original root cause of a error back to a caller
so
that the caller can deal with it. This extension is only semantically useful
in Response and Fault PDUs.
It is intended that this error information is suitable for displaying
information to a human being who is the user; this information is not
Brown/Kindel page
27
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
intended to be the basis for logic decisions in a piece of client code, for
doing so couples the client code to the implementation of the server.
Rather,
client code should act semantically only on the information returned through
the interface that it invokes.
Further details TBS.
4. IRemUnknown and IRemUnknown2 interfaces
The IRemUnknown interface is used by remote clients for manipulating
reference counts on the IPIDs that they hold and for obtaining additional
interfaces on the objects on which those IPIDs are found.
References are kept per interface rather then per object.
This interface is implemented by the COM "OXID object" associated with each
OXID (i.e. each Object Exporter). The IPID for the IRemUnknown interface on
this object is returned from IOXIDResolver::ResolveOxid (see Section 5.2.1),
or when an object is activated with IRemoteActivation::RemoteActivation (see
section 6.2.1). An OXID object need never be pinged; its interfaces (this
IPID included) need never be reference counted. IRemUnknown is specified as
follows:
The IRemUnknown2 interface introduced in version 5.2 of the DCOM protocol
inherits from IRemUnknown and adds an extra method –- RemoteQueryInterface2
–
- which allows clients to retrieve interface pointers to objects which
supply
additional data beyond the STDOBJREF in their marshaled interface packets.
// The remote version of IUnknown. This interface exists on every
// OXID (whether an OXID represents either a thread or a process is
// implementation specific). It is used by clients to query for new
// interfaces, get additional references (for marshaling), and release
// outstanding references.
// This interface is passed along during OXID resolution.
//
[
object,
uuid(00000131-0000-0000-C000-000000000046)
]
interface IRemUnknown : IUnknown
{
typedef struct tagREMQIRESULT
Brown/Kindel page
28
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
{
HRESULT hResult; // result of call
STDOBJREF std; // data for returned interface
} REMQIRESULT;
HRESULT RemQueryInterface
(
[in] REFIPID ripid, // interface to QI on
[in] unsigned long cRefs, // count of AddRefs requested
[in] unsigned short cIids, // count of IIDs that follow
[in, size_is(cIids)]
IID* iids, // IIDs to QI for
[out, size_is(,cIids)]
REMQIRESULT** ppQIResults // results returned
);
typedef struct tagREMINTERFACEREF
{
IPID ipid; // ipid to AddRef/Release
unsigned long cPublicRefs;
unsigned long cPrivateRefs;
} REMINTERFACEREF;
HRESULT RemAddRef
(
[in] unsigned short cInterfaceRefs,
[in, size_is(cInterfaceRefs)]
REMINTERFACEREF InterfaceRefs[],
[out, size_is(cInterfaceRefs)]
HRESULT* pResults
);
HRESULT RemRelease
(
[in] unsigned short cInterfaceRefs,
[in, size_is(cInterfaceRefs)]
REMINTERFACEREF InterfaceRefs[]
);
}
// Derived from IRemUnknown, this interface supports Remote Query interface
// for objects that supply additional data beyond the STDOBJREF in their
Brown/Kindel page
29
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
// marshaled interface packets.
[
object,
uuid(00000142-0000-0000-C000-000000000046)
]
interface IRemUnknown2 : IRemUnknown
{
#ifndef DO_NO_IMPORTS
import "unknwn.idl";
import "obase.idl";
#endif
HRESULT RemQueryInterface2
(
[in] REFIPID ripid,
[in] unsigned short cIids,
[in, size_is(cIids)] IID *iids,
[out, size_is(cIids)] HRESULT *phr,
[out, size_is(cIids)] MInterfacePointer **ppMIF
);
}
4.1 IRemUnknown::RemQueryInterface
QueryInterface for and return the result thereof for zero or more interfaces
from the interface behind the IPID ipid. ipid must designate an interface
derived from IUnknown (recall that all remoted interfaces must derive from
IUnknown). The QueryInterface calls on the object that are used to service
this request are conducted on the IUnknown interface of the object.
Argument Type Semantic
ripid REFIPID The interface on an object from whom more
interfaces are desired.
cRefs unsigned long The number of references sought on each of
the
returned IIDs.
cIids unsigned short The interfaces being requested.
iids IID* The list of IIDs that name the interfaces
sought on this object.
ppQIResults REMQIRESULT** The place at which the array of the results
of
the various QueryInterface calls are
returned.
Brown/Kindel page
30
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
ReturnValue Meaning
S_OK Success. An attempt was made to retrieve each of the
requested interfaces from the indicated object; that
is, QueryInterface was actually invoked for each
IID.
QueryInterface returned S_OK for every IID
specified.
S_FALSE Success. An attempt was made to retrieve each of the
requested interfaces from the indicated object; that
is, QueryInterface was actually invoked for each
IID.
QueryInterface returned a failure code for at least
one of the IIDs specified.
E_NOINTERFACE QueryInterface returned a failure code for every IID
specifed.
E_INVALIDARG One or more arguments (likely ipid) were invalid. No
result values are returned.
E_UNEXPECTED An unspecified error occurred.
E_OUTOFMEMORY Insufficient memory to complete the call.
RPC_E_INVALID_OBJECT The requested object does not exist. No result
values
are returned.
4.1.1 REMQIRESULT
The REMQIRESULT structure contains the following members:
Member Type Semantic
hResult HRESULT The result code from the QueryInterface call made
for the requested IID.
std STDOBJREF The data for the returned interface. Note that if
hResult indicates failure then the contents of
STDOBJREF are undefined.
4.2 IRemUnknown2::RemQueryInterface2
Like RemQueryInterface, this method queries for zero or more interfaces from
the interface behind the IPID ipid. Instead of returning the STDOBJREF
marshaled interface packet, this method can return any marshaled data packet
in the form of a blob of bytes (including the traditional STDOBJREF).
Argument Type Semantic
ripid REFIPID The interface on an object from whom more
Brown/Kindel page
31
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
interfaces are desired.
cIids unsigned short The number of references sought on each of
the returned IIDs.
iids IID* The interfaces being requested.
phr HRESULT* The result code returned from
QueryInterface() on each interface in the
iids array.
ppMIF MinterfacePointer** The marshaled interface packet for each of
the IIDs requested.
ReturnValue Meaning
S_OK Success. An attempt was made to retrieve each of the
requested interfaces from the indicated object; that
is, QueryInterface was actually invoked for each IID.
QueryInterface returned S_OK for every IID specified.
S_FALSE Success. An attempt was made to retrieve each of the
requested interfaces from the indicated object; that
is, QueryInterface was actually invoked for each IID.
QueryInterface returned a failure code for at least
one of the IIDs specified.
E_NOINTERFACE QueryInterface returned a failure code for every IID
specifed.
E_INVALIDARG One or more arguments (likely ipid) were invalid. No
result values are returned.
E_UNEXPECTED An unspecified error occurred.
E_OUTOFMEMORY Insufficient memory to complete the call.
RPC_E_INVALID_OBJECT The requested object does not exist. No result values
are returned.
4.3 IRemUnknown::RemAddRef
Obtain and grant ownership to the caller of one or more reference counts on
one or more IPIDs managed by the corresponding OXID.
Argument Type Semantic
cInterfaceRefs unsigned short The size of the rgRefs array.
InterfaceRefs REMINTERFACEREF[] An array of REMINTERFACEREFs, cRefs
large. Each IPID indicates an interface
managed by this OXID on whom more
reference counts are sought. The
corresponding reference count
Brown/Kindel page
32
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
(cInterfaceRefs), which may not be zero
(and thus is one or more), indicates the
number of reference counts sought on
that IPID.
pResults HRESULT* An array of HRESULTs cInterfaceRefs
large, each containing the result of
attempting an AddRef on the ipid in the
corresponding REMINTERFACREF.
Return Value Meaning
S_OK Success. An attempt was made to retrieve each of the
requested
interface references.
E_INVALIDARG One or more of the IPIDs indicated were not in fact managed
by
this OXID, or one or more of the requested reference counts
was zero. None of the requested reference counts have been
granted to the caller; the call is a no-op.
E_UNEXPECTED An unspecified error occurred. It is unknown whether any or
all of the requested reference counts have been granted.
CO_E_OBJNOTREG Object is not registered.
A useful optimization is for a caller to RemAddRef more than needed.
When a process receives an out marshaled interface, it receives one
reference
count. If the process wishes to pass that interface as an out parameter, it
must get another reference to pass along. Instead, the process (or
middleman)
should get a large number of references. Then if the interface is passed out
multiple times, no new remote calls are needed to gain additional
references.
A marshaler may optionally specify more than one reference in the STDOBJREF
when marshaling an interface. This allows the middle man case to pre-fill
its
cache of references without making an extra RemAddRef call. The number of
references passed is always specified in the STDOBJREF field.
If cPrivateRefs is not zero for all IPIDs, the call to RemAddRef must be
made
securely. DCOM on the server remembers the name of the client and the
authentication and authorization service used to make to RemAddRef call.
4.3.1 REMINTERFACEREF
Member Type Semantic
ipid IPID ipid to AddRef/Release.
cPublicRefs unsigned long Number of public references granted.
cPrivateRefs unsigned long Number of private references granted. Private
references belong only to this client and can
Brown/Kindel page
33
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
not be passed to other clients when marshaling
the proxy. If a client has only private
references and wishes to pass the proxy to
some
other client, it must first obtain some public
references via IRemUnknown::RemAddRef and then
pass one or more of those references in the
STDOBJREF cPublicRefs field of the marshaled
interface.
4.4 IRemUnknown::RemRelease
Release ownership of one or more reference counts on one or more IPIDs
managed by the corresponding OXID.
If cPrivateRefs is not zero for all IPIDs, the call to RemRelease must be
made securely. For each IPID, DCOM maintains a table of reference counts
indexed by the client identity (name, authn svc, authz svc). All public
references are stored in one entry. Any call to RemRelease can release
public references. Private references can only be released by the client
that added them.
Argument Type Semantic
cRefs unsigned short The size of the rgRefs array.
rgRefs REMINTERFACEREF[] An array of REMINTERFACEREFs, cRefs large.
Each
IPID indicates an interface managed by this
OXID on whom more reference counts are being
returned. The corresponding reference count,
which may not be zero (and thus is one or
more), indicates the number of reference
counts
returned on that IPID.
Return Value Meaning
S_OK Success. An attempt was made to release each of the requested
interface references.
E_INVALIDARG One or more of the IPIDs indicated were not in fact managed by
this OXID, or one or more of the requested reference counts was
zero. None of the offered reference counts have been accepted
by
the server; the call is a no-op.
E_UNEXPECTED An unspecified error occurred. It is unknown whether any or all
of the offered reference counts have been accepted.
Brown/Kindel page
34
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
5. The OXID Resolver
Each machine that supports the COM network protocol supports a one- per-
machine service known as the machine's `OXID Resolver.' Communication with
an
OXID Resolver is via a DCE RPC, not an ORPC.
The OXID Resolver performs several services:
@ It caches and returns to clients when asked the string bindings necessary
to connect to OXIDs of exported objects for which this machine is either
itself a client or is the server. Note that it typically returns only to
client processes on the same machine as itself, the OXIDs for which it is
a
client.
@ It receives pings from remote client machines to keep its own objects
alive.
@ May do lazy protocol registration in the servers which it scopes.
These services are carried out through an RPC interface (not a COM
interface)
known as IOXIDResolver. An OXID Resolver may be asked for the information
required to connect to one of two different kinds of OXIDs, either the OXIDs
associated with its own objects, or the OXIDs associated with objects for
which it is itself a client The second case occurs when two or more client
processes on the same machine ask their local OXID Resolver to resolve a
given OXID. The client OXID Resolver in this case can cache the OXID
information an return it to local clients without having to contact the
server’s OXID Resolver again.
5.1 OXID Resolver Ports/Endpoints
The OXID Resolver resides at different endpoints (ports) depending on the
transport being used. The OXID Resolver optimally resides at the same
endpoints as the DCE RPC Endpoint Mapper (EPM). To accommodate systems where
DCOM will coexist with existing DCE RPC installations (i.e., where an EPM
and
presumably a complete DCE RPC runtime already exists), the DCOM
implementation on that system will register its interfaces with the DCE EPM
and all DCOM implementations must be able to fall back if they make DCOM-
specific calls on the DCE EPM endpoint which fail.
Protocol String Description Endpoint
Name(s)
ncadg_ip_udp, ip CL over UDP/IP 135
ncacn_ip_tcp CO over TCP/IP 135
ncadg_ipx CL over IPX TBD
Brown/Kindel page
35
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
ncacn_spx CO over SPX TBD
ncacn_nb_nb CO over NetBIOS over NetBEUI TBD
ncacn_nb_ipx CO over IPX TBD
ncacn_http CO over HTTP 593
5.2 The IOXIDResolver Interface
IOXIDResolver (in earlier DCOM documentation this interface was named
IObjectExporter) is defined as follows:
[
uuid(99fcfec4-5260-101b-bbcb-00aa0021347a),
pointer_default(unique)
]
interface IOXIDResolver
{
// Method to get the protocol sequences, string bindings
// and machine id for an object server given its OXID.
[idempotent] error_status_t ResolveOxid
(
[in] handle_t hRpc,
[in] OXID *pOxid,
[in] unsigned short cRequestedProtseqs,
[in, ref, size_is(cRequestedProtseqs)]
unsigned short arRequestedProtseqs[],
[out, ref] DUALSTRINGARRAY **ppdsaOxidBindings,
[out, ref] IPID *pipidRemUnknown,
[out, ref] DWORD *pAuthnHint
);
// Simple ping is used to ping a Set. Client machines use this
// to inform the object exporter that it is still using the
// members of the set.
// Returns S_TRUE if the SetId is known by the object exporter,
// S_FALSE if not.
[idempotent] error_status_t SimplePing
(
[in] handle_t hRpc,
[in] SETID *pSetId // Must not be zero
);
// Complex ping is used to create sets of OIDs to ping. The
Brown/Kindel page
36
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
// whole set can subsequently be pinged using SimplePing,
// thus reducing network traffic.
[idempotent] error_status_t ComplexPing
(
[in] handle_t hRpc,
[in, out] SETID *pSetId, // In of 0 on first
// call for new set.
[in] unsigned short SequenceNum,
[in] unsigned short cAddToSet,
[in] unsigned short cDelFromSet,
[in, unique, size_is(cAddToSet)] OID AddToSet[],
// add these OIDs to the set
[in, unique, size_is(cDelFromSet)] OID DelFromSet[],
// remove these OIDs from the set
[out] unsigned short *pPingBackoffFactor
// 2^factor = multipler
);
// In some cases the client maybe unsure that a particular
// binding will reach the server. (For example, when the oxid
// bindings have more then one TCP/IP binding) This call
// can be used to validate the binding
// from the client.
[idempotent] error_status_t ServerAlive
(
[in] handle_t hRpc
);
// Method to get the protocol sequences, string bindings, RemoteUnknown
IPID
// and COM version for an object server given its OXID. Supported by
DCOM
// version 5.2 and above.
[idempotent] error_status_t ResolveOxid2
(
[in] handle_t hRpc,
[in] OXID *pOxid,
[in] unsigned short cRequestedProtseqs,
[in, ref, size_is(cRequestedProtseqs)]
unsigned short arRequestedProtseqs[],
[out, ref] DUALSTRINGARRAY **ppdsaOxidBindings,
[out, ref] IPID *pipidRemUnknown,
Brown/Kindel page
37
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
[out, ref] DWORD *pAuthnHint,
[out, ref] COMVERSION *pComVersion
);
}
5.2.1 IOXIDResolver::ResolveOxid and IOXIDResolver::ResolveOxid2
Return the string bindings necessary to connect to a given OXID object.
On entry, arRequestedProtseqs contains the protocol sequences the client is
willing to use to reach the server. These should be in decreasing order of
protocol preference, with no duplicates permitted. Local protocols (such as
"ncalrpc") are not permitted.
On exit, psaOxidBindings contains the string bindings that may be used to
connect to the indicated OXID; if no such protocol bindings exist which
match
the requested protocol sequences, NULL may be returned. The returned string
bindings are in decreasing order of preference of the server, with duplicate
string bindings permitted (and not necessarily of the same preferential
priority), though of course duplicates are of no utility. Local protocol
sequences may not be present; however, protocol sequences that were not in
the set of protocol sequences requested by the client may be. The string
bindings returned need not contain endpoints; the endpoint mapper will be
used as usual to obtain these dynamically.
Version 5.2 of the DCOM wire protocol introduces a new method called
ResolveOXID2 which allows a client to determine the version of a server’s
COM
implementation when it asks for OXID resolution. All clients must attempt to
call this method to make sure that the major version of the server is one
which they are capable of supporting. Clients who call this method and get
an
RPC_S_PROCNUM_OUT_OF_RANGE error can assume that the server supports version
5.1 of the DCOM wire protocol. If the method call does succeed, the client
should compare pComVersion->MajorVersion with the major version(s) that the
client supports. If the client does not explicitly support the major version
returned by the server, it should disconnect.
The major version combined with the lower of the client’s and server’s minor
versions should be inserted into the ORPCTHIS structure when issuing an ORPC
to the server.
Please see the IDL section above for notes on the differences between the
minor versions of the DCOM wire protocol.
Brown/Kindel page
38
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
Argument Type Description
hRpc handle_t An RPC binding handle used to make the
request.
pOxid OXID* The OXID for whom string bindings are
requested.
cRequestedProtseqs unsigned The number of protocol sequences
short requested.
arRequestedProtseqs unsigned arRequestedProtseqs must be initialized
short[] with all the protocol id's the client
is
willing to use to reach the server. It
cannot contain local protocol
sequences.
The object exporter must take care of
local lookups privately. The protocol
sequences are in order of preference or
random order. No duplicates are
allowed.
See the Lazy Protocol Registration
section for more details.
psaOxidBindings STRINGARRAY** The string bindings supported by this
OXID, in preferential order. Note that
these are Unicode strings.
pipidRemUnknown IPID* The IPID to the IRemUnknown interface
the
OXID object for this OXID.
pdwAuthnHint unsigned A value taken from the RPC_C_AUTHN
long* constants. A hint to the caller as to
the
minimum authentication level which the
server will accept.
pComVersion COMVERSION* [ResolveOxid2 Only] A structure
containing the major and minor version
of
the COM implementation on the server.
Return Value Meaning
S_OK Success. The requested information was returned.
RPC_S_PROCNUM_OUT_OF_RANGE The procedure number is out of range (i.e. the
function is not implemented).
RPC_E_INVALID_OXID This OXID is unknown to this OXID Resolver, and
thus no information was returned.
E_UNEXPECTED An unspecified error occurred. Some of the
requested information may not be returned.
Brown/Kindel page
39
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
Object references are transient things. They are not meant to be stored in
files or otherwise kept persistently.
Conversely, since object references are aged, it is the responsibility of
each client to unmarshal them and begin pinging them in a timely fashion.
The basic use of the ResolveOxid method is to translate an OXID to string
bindings. Put another way, this method translates an opaque process and
machine identifier to the information needed to reach that machine and
process. There are four interesting cases:
1. Looking up an OXID the first time an interface is unmarshaled on a
machine,
2. Looking up an OXID between a pair of machines that already have
connections,
3. Looking up an OXID from a middleman, and
4. Looking up string bindings with unresolved endpoints (lazy use protseq).
Another interesting topic is garbage collection of stored string binding
vectors.
5.2.1.2 Lookup Between Friends
Consider the case with two machines A and B. Machine A has a client process
C
and and OXID Resolver process D. Machine B has OXID Resolver process E and
server process F.
Server process F, when it starts up, registers it’s RPC string bindings with
its local OXID Resolver process E, and creates an OBJREF to some object
inside process F. At some future time client process C receives that OBJREF
(Note: the mechanism used to acquire this OBJREF is not relevant to this
discussion, it may have come through the object activation protocol (beyond
the scope of this document) or as an [out] interface parameter in some other
ORPC call, or through some other mechanism). The OBJREF contains the OXID
for
process F, and the string bindings for the Resolver process E on the server
machine.
Client Process C asks its local OXID Resolver to resolve the OXID for F. It
passes it the OXID and the string bindings for OXID Resolver E. If Resolver
D
has never seen the OXID before, it calls the OXID Resolver E to ask it to
resolve the OXID. Resolver E looks up the OXID and returns the string
bindings for server process F. Resolver D then caches this information for
future use, and returns the string bindings to client process C. Client
process C then binds to the string bindings and is now able to make ORPC
calls directly to the server process F.
Brown/Kindel page
40
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
If other client processes on machine A receive an OBJREF for process F, the
OXID resolve can be handled completely by the Resolver process D on machine
A. There is no need to contact Resolver process E on the server again.
If machine A gives an OBJREF for F to a client process on another machine G,
then the Resolver process on G will repeat the same steps as Resolver
process
D did to resolve the OXID.
+============+============+ +===========+===========+
| Machine A | | Machine B |
+============+============+ +===========+===========+
+============+============+ +===========+===========+
| Process C | Resolver D | | Resolver E| Process F |
+============+============+ +===========+===========+
| | | | | register |
| | | | | endpoints |
| | | | | with local|
| | | | | Resolver E|
+------------+------------+ +-----------+-----------+
| | | | cache F | |
| | | | and it’s | |
| | | | endpoints | |
| | | | | |
+------------+------------+ +-----------+-----------+
| receive | | | | |
| OBJREF | | | | |
| to F | | | | |
| | | | | |
+------------+------------+ +-----------+-----------+
| ask local | | | | |
| Resolver D | | | | |
| to resolve | | | | |
| F | | | | |
+------------+------------+ +-----------+-----------+
| | ask remote | | | |
| | Resolver | | | |
| | E to | | | |
| | resolve F | | | |
+------------+------------+ +-----------+-----------+
| | | | lookup F | |
| | | | and | |
| | | | return | |
Brown/Kindel page
41
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
| | | | endpoints | |
+------------+------------+ +-----------+-----------+
| | cache | | | |
| | endpoints | | | |
| | to F and | | | |
| | return to C| | | |
+------------+------------+ +-----------+-----------+
| bind to | | | | |
| endpoint | | | | |
| for F | | | | |
| | | | | |
+------------+------------+ +-----------+-----------+
| invoke | | | | |
| method on | | | | |
| F | | | | |
| | | | | |
+------------+------------+ +-----------+-----------+
5.2.1.4 Lazy Protocol Registration
In a homogeneous network, all machines communicate via the same protocol
sequence. In a heterogeneous network, machines may support multiple protocol
sequences. Since it is often expensive in resources to allocate endpoints
(RpcServerUseProtseq) for all available protocol sequences, ORPC provides a
mechanism where they may be allocated on demand. To implement this extension
fully, there are some changes in the server. However, changes are optional.
If not implemented, ORPC will still work correctly if less optimally in
heterogeneous networks.
There are two cases: the server implements lazy protocol registration or it
does not.
If the server is using lazy protocol registration, the implementation of
ResolveOxid is modified slightly. When the client OXID Resolver calls the
server OXID Resolver, it passes the requested protocol sequence vector. If
none of the requested protocol sequences have endpoints allocated in the
server, the server OXID Resolver allocates them according to its own
endpoint
allocation mechanisms.
If the server does not implement the lazy protocol registration, then all
protocol sequences are registered by the server at server initialization
time.
Brown/Kindel page
42
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
When registering protocol sequences, the server may register endpoints and
the server’s string bindings will contain the complete endpoints. However,
if the server chooses not register endpoints when it registers protocol
sequences the endpoint mapper process can be used to forward calls to the
server. Using the endpoint mapper requires that all server IIDs be
registered
in the endpoint mapper. It also allows a different lazy protocol
registration
mechanism. The endpoint mapper can perform some local magic to force the
server to register the protocol sequences.
The client will always pass in a vector of requested protocol sequences
which
the server can ignore if it does not implement lazy protocol registration.
5.2.2 IOXIDResolver::SimplePing
Pings provide a mechanism to garbage collect interfaces. If an interface has
references but is not being pinged, it may be released. Conversely, if an
interface has no references, it may be released even though it has recently
been pinged. SimplePing just pings the contents of a set. The set must be
created with ComplexPing (section 5.2.3).
Ping a set, previously created with IOXIDResolver::ComplexPing, of OIDs
owned
by this OXID Resolver. Note that neither IPIDs nor OIDs may be pinged, only
explicitly created SETIDs.
Argument Type Description
hRpc handle_t An RPC binding handle used to make the request.
PSetId SETID* A SETID previously created with
IOXIDResolver::ComplexPing on this same OXID Resolver.
Return Value Meaning
S_OK Success. The set was pinged.
RPC_E_INVALID_SET This SETID is unknown to this OXID Resolver, and thus the
ping did not occur.
E_UNEXPECTED An unspecified error occurred. It is not known whether
the
ping was done or not.
5.2.3 IOXIDResolver::ComplexPing
Ping a ping set. Optionally, add and/or remove some OIDs from the set.
Optionally, adjust some ping timing parameters associated with the set.
After
a set is defined, a SimplePing will mark the entire contents of the set as
Brown/Kindel page
43
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
active. After a set is defined, SimplePing should be used to ping the set.
ComplexPing need only be used to adjust the contents of the set (or to
adjust
the time-out).
Ping set ids (SETIDs) are allocated unilaterally by the server OXID
Resolver. The client OXID Resolver then communicates with the server OXID
Resolver to add (and later remove) OIDs from the ping set..
Each OID owned by a server OXID Resolver may be placed in zero or more ping
sets by the various clients of the OID. The client owner of each such set
will set a ping period and a ping time-out count for the set, thus
determining an overall time-out period for the set as the product of these
two values. The time-out period is implicitly applied to each OID contained
in the set and to future OIDs that might add be added to it. The server OXID
Resolver is responsible for ensuring that an OID that it owns does not
expire
until at least a period of time t has elapsed without that OID being pinged,
where t is the maximum time-out period over all the sets which presently
contain the given OID, or, if OID is not presently in any such sets but was
previously, t is the time-out period for the last set from which OID was
removed at the instant that that removal was done; otherwise, OID has never
been in a set, and t is a default value (ping period equals 120 seconds,
ping
time-out count equals three (3), t equals 360 seconds, or six (6) minutes).
Clients are responsible for pinging servers often enough to ensure that they
do not expire given the possibility of network delays, lost packets, and so
on. If a client only requires access to a given object for what it would
consider less than a time-out period for the object (that is, it receives
and
release the object in that period of time), then unless it is certain it has
not itself passed the object to another client, it must be sure to
nevertheless ping the object (a ComplexPing that both adds and removes the
OID will suffice). This ensures that an object will not expire as it is
passed through a chain of calls from one client to another.
An OID is said to be pinged when a set into which it was previously added
and
presently still resides is pinged with either a SimplePing or a ComplexPing,
or when it is newly added to a set with ComplexPing. Note that these rules
imply that a ComplexPing that removes an OID from a set still counts as a
ping on that OID. In addition to pinging the set SETID, this call sets the
time-out period of the set as the product of a newly-specified ping period
and a newly-specified "ping count to expiration;" these values take effect
immediately. Ping periods are specified in tenths of a second, yielding a
maximum allowable ping period of about 1 hr 50 min.
Adjustment of the time-out period of the set is considered to happen before
the addition of any new OIDs to the set, which is in turn considered to
happen before the removal of any OIDs from the set. Thus, an OID that is
Brown/Kindel page
44
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
added and removed in a single call no longer resides in the set, but is
considered to have been pinged, and will have as its time-out at least the
time-out period specified in that ComplexPing call.
On exit, the server may request that the client adjust the time-out period;
that is, ask it to specify a different time-out period in subsequent calls
to
ComplexPing. This capability can be used to reduce traffic in busy servers
or
over slow links. The server indicates its desire through the values it
returns through the variables pReqSetPingPeriod and
pReqSetNumPingsToTimeOut.
If the server seeks no change, it simply returns the corresponding values
passed by the client; if it wishes a longer time-out period, it indicates
larger values for one or both of these variables; if it wishes a smaller
period, it indicates smaller values. When indicating a larger value, the
server must start immediately acting on that larger value by adjusting the
time-out period of the set. However, when indicating a smaller value, it
must
consider its request as purely advice to the client, and not take any
action:
if the client wishes to oblige, it will do so in a subsequent call to
ComplexPing by specifying an appropriate time-out period.
Argument Type Description
hRpc handle_t An RPC binding handle used to make the
request.
pSetId SETID The SETID being manipulated. SequenceNum
unsigned short The sequence number allows
the object exporter to detect duplicate
packets. Since the call is idempotent, it
is
possible for duplicates to get executed and
for calls to arrive out of order when one
ping is delayed.
cAddToSet unsigned The size of the array AddToSet.
short
cDelFromSet unsigned The size of the array DelFromSet.
short
AddToSet OID[] The list of OIDs which are to be added to
this set. Adding an OID to a set in which
it
already exists is permitted; such an
action,
as would be expected, is considered to ping
the OID.
DelFromSet OID[] The list of OIDs which are to be removed
from this set. Removal counts as a ping. An
OID removed from a set will expire after
the
number of ping periods has expired without
Brown/Kindel page
45
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
any pings (not the number of ping periods -
1). If an id is added and removed from a
set
in the same ComplexPing, the id is
considered to have been deleted.
pPingBackoffFactor unsigned Acts as a hint (only) from the server to
the
short* client in order to reduce ping traffic.
Clients are requested to not ping more
often
than (1<<*pPingBackoffFactor)*
(BasePingInterval=120) seconds, and the
number of pings until timeout remains
unchanged at the default of 3. Clients may
choose to assume that this parameter is
always zero.
Return Value Meaning
S_OK Success. The set was pinged, etc.
RPC_E_INVALID_OID Indicates that some OID was not recognized. There is no
recovery action for this error, it is informational only.
E_ACCESSDENIED Access is denied.
E_OUTOFMEMORY There was not enough memory to service the call. The
caller may retry adding OIDs to the set on the next ping.
E_UNEXPECTED An unspecified error occurred. It is not known whether
the
ping or any of the other actions were done or not.
6. Object Activation
Each machine that supports the COM network protocol also supports a one-per-
machine interface called IRemoteActivation (which supersedes ISCMtoSCM in
previous drafts of this document). This interface contains one method –-
RemoteActivation –- used to activate a class object associated with a
caller-
supplied CLSID, file moniker, or IStorage pointer.
6.1 IRemoteActivation Ports/Endpoints
IRemoteActivation resides at the same endpoints as the IOXIDResolver
interface. Please see section 5.1 for more information.
Brown/Kindel page
46
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
6.2 The IRemoteActivation Interface
IRemoteActivation is defined as follows:
[
uuid(4d9f4ab8-7d1c-11cf-861e-0020af6e7c57),
pointer_default(unique)
]
interface IRemoteActivation
{
import "obase.idl";
const unsigned long MODE_GET_CLASS_OBJECT = 0xffffffff;
HRESULT RemoteActivation(
[in] handle_t hRpc,
[in] ORPCTHIS *ORPCthis,
[out] ORPCTHAT *ORPCthat,
[in] GUID *Clsid,
[in, string, unique] WCHAR *pwszObjectName,
[in, unique] MInterfacePointer *pObjectStorage,
[in] DWORD ClientImpLevel,
[in] DWORD Mode,
[in] DWORD Interfaces,
[in,unique,size_is(Interfaces)] IID *pIIDs,
[in] unsigned short cRequestedProtseqs,
[in, size_is(cRequestedProtseqs)]
unsigned short RequestedProtseqs[],
[out] OXID *pOxid,
[out] DUALSTRINGARRAY **ppdsaOxidBindings,
[out] IPID *pipidRemUnknown,
[out] DWORD *pAuthnHint,
[out] COMVERSION *pServerVersion,
[out] HRESULT *phr,
[out,size_is(Interfaces)] MInterfacePointer **ppInterfaceData,
[out,size_is(Interfaces)] HRESULT *pResults
);
}
6.2.1 IRemoteActivation::RemoteActivation
Brown/Kindel page
47
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
Activates the class object specified by Clsid, associated with the
pwszObjectName file moniker, or associated with pObjectStorage -- a client-
provided IStorage object --, and gives the client the OXID and IPID(s) of
any
interfaces it requested on that object. Implementations are free to return a
new instance of the requested class object every time this API is called or
to return the same class object (i.e. the same OXID and IPIDs) every time.
Implementations may choose to offer “launch” functionality by loading and
initializing the executable code which implements the requested class object
if it is not already running, or if the programmer wishes to have objects
segregated into different processes because of security or robustness
considerations.
This function incorporates the functionality of both the IRemUnknown and
IOXIDResolver interfaces so that only one network roundtrip is necessary for
object activation.
Argument Type Description
hRpc handle_t An RPC binding handle used to make
the request.
ORPCthis ORPCTHIS* Client-provided ORPCTHIS
ORPCthat ORPCTHAT* Server-provided ORPCTHAT
Clsid const GUID* The CLSID of the class object the
caller wishes to activate.
pwszObjectName WCHAR* Path to a file name which when
activated by the server’s moniker
facility, will return the object
that the client is interested in.
pObjectStorage MInterfacePointer* Interface pointer to an object on
the client which supports
IStorage.
The server on the remote will use
the IStorage’s CLSID to determine
which object to instantiate on the
server.
ClientImpLevel DWORD A value taken from the RPC_C_IMP
constants. Used to inform the
server of the client’s default
impersonation level.
Mode DWORD Set to MODE_GET_CLASS_OBJECT for
regular object activations. If
pwszObjectName or pObjectStorage
are not NULL, this mode is passed
Brown/Kindel page
48
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
to IPersistFile::Load when
activating the object on the
server.
Interfaces DWORD The number of interfaces being
requested.
pIIDs IID* The list of IIDs that name the
interfaces sought on this object.
cRequestedProtseqs Unsigned short The number of protocol sequences
specified in the RequestedProtseqs
parameter.
RequestedProtseqs Unsigned short[] The list of protocol sequences
that
the client wants OXID binding
handles for.
pOxid OXID* The OXID for the object created.
ppdsaOxidBindings DUALSTRINGARRAY** Endpoint and security binding
strings to reach the OXID
pipidRemUnknown IPID* The IPID of the OXID’s IRemUnknown
interface
pAuthnHint DWORD* A value taken from the RPC_C_AUTHN
constants. A hint to the caller as
to the minimum authentication
level
which the server will accept.
pServerVersion COMVERSION* The version of the COM
implementation on the server.
phr HRESULT* The HRESULT for the activation
operation
ppInterfaceData MInterfacePointer** The set of interface pointers
requested. Returned in the order
they were requested in pIIDs.
pResults HRESULT* The HRESULTs for the individual
QueryInterface() operations
performed on the interfaces
specified in Interfaces.
Return Value Meaning
RPC_S_OK This method always returns RPC_S_OK. Check phr for the
status of this function.
Value of phr Meaning
E_UNEXPECTED An unspecified error occurred.
E_ACCESSDENIED Client attempted to activate but did not have the
required permission or the server does not permit
Brown/Kindel page
49
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
remote activations.
E_INVALIDARG One or more arguments are invalid.
E_OUTOFMEMORY Insufficient memory to complete the operation.
7. Security Considerations
In general, like any generic data transfer protocol, DCOM cannot regulate
the
content of the data that is transferred, nor is there any a priori method of
determining the sensitivity of any particular piece of information within
the
context of any given ORPC.
Specifically, however, DCOM entirely leverages the security infrastructure
defined by DCE RPC, which allows for various forms of authentication,
authorization, and message integrity.
Further details TBS.
8. Acknowledgements
As previously noted, the DCOM protocol highly leverages the DCE RPC
Specification [CAE RPC], and we again acknowledge its usefulness to this
specification.
The DCOM protocol itself is the combined effort of a large number of people.
The following individuals in particular were critical to the definitions
which appear in this specification.
Bob Atkinson Alex Armanasu (Mitchell)
Deborah Black Vibhas Chandorkar
Richard Draves Mario Goertzel
Rick Hill Gregory Jensenworth
David Kays Paul Leach
Michael Nelson Kevin Ross
Mark Ryland Bharat Shah
Tony Williams
9. References
[CAE RPC] CAE Specification, X/Open DCE: Remote Procedure Call, X/Open
Company Limited, Reading, Berkshire, UK (xopen.co.uk), 1994. X/Open
Document Number C309. ISBN 1-85912-041-5. (also available online
through
from the OSF at <http://www.opengroup.org/tech/dce/download>)
Brown/Kindel page
50
Internet Draft <draft-brown-dcom-v1-spec-02.txt> January,
1998
[COM] The Component Object Model Specification, Version 0.99, November,
1996,
Microsoft Corporation. (also available online from Microsoft at
<http://www.microsoft.com/oledev/olecom/title.htm>. Note that this
reference is circular because this document (the DCOM wire protocol
specification) is the same chapter 15 of the COM Specification.
10. Author's Addresses
Nat Brown, One Microsoft Way Redmond, WA 98052-6399, U.S.A. Fax: +1 (206)
936
7329 Email: <mailto:natbro@microsoft.com>
Charlie Kindel, One Microsoft Way Redmond, WA 98052-6399, U.S.A. Fax: +1
(206) 936 7329 Email: <mailto:ckindel@microsoft.com>
Brown/Kindel page
51Original