idnits 2.17.1 draft-brown-dcom-v1-spec-03.txt: -(438): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(1339): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(1866): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(1878): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(1975): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(2103): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(2308): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(2379): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(2398): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(2405): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(2410): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(2440): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-26) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == There are 16 instances of lines with non-ascii characters in the document. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 5 longer pages, the longest (page 2) being 2550 lines == It seems as if not all pages are separated by form feeds - found 0 form feeds but 9 pages Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 578 instances of too long lines in the document, the longest one being 5 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 233 has weird spacing: '... to the serve...' == Line 311 has weird spacing: '...esolver which...' == Line 312 has weird spacing: '...ference for t...' == Line 415 has weird spacing: '...ound on the O...' == Line 556 has weird spacing: '...into sets kno...' == (36 more instances...) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- Couldn't find a document date in the document -- date freshness check skipped. -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Non-RFC (?) normative reference: ref. 'CAE RPC' -- Possible downref: Non-RFC (?) normative reference: ref. 'COM' Summary: 7 errors (**), 0 flaws (~~), 10 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Network Working Group Nat Brown 2 INTERNET-DRAFT Charlie Kindel 3 Microsoft Corporation 4 Expires in six months January, 1998 6 Distributed Component Object Model Protocol -- DCOM/1.0 8 Status of this Memo 10 This document is an Internet-Draft. Internet-Drafts are working documents of 11 the Internet Engineering Task Force (IETF), its areas, and its working 12 groups. Note that other groups may also distribute working documents as 13 Internet-Drafts. 15 Internet-Drafts are draft documents valid for a maximum of six months and 16 may 17 be updated, replaced, or obsoleted by other documents at any time. It is 18 inappropriate to use Internet-Drafts as reference material or to cite them 19 other than as "work in progress." 21 To learn the current status of any Internet-Draft, please check the "1id- 22 abstracts.txt" listing contained in the internet-drafts Shadow Directories 23 at 24 (Africa), 25 (Europe), (Pacific Rim), 27 (US East Coast), or 28 (US West Coast). 30 Distribution of this document is unlimited. Please send comments to the 31 authors at . General discussions about DCOM 32 and 33 its applications should take place on the DCOM mailing list. To subscribe, 34 send a piece of mail to . Leave the subject 35 blank and in the body of the message, first type "subscribe" for non-digest 36 or "digest" for digest version, followed by "DCOM", and finally by your 37 name. 38 (example: "subscribe DCOM John Doe"). 40 Abstract 42 The Distributed Component Object Model protocol is an application-level 43 protocol for object-oriented remote procedure calls useful for distributed, 44 component-based systems of all types. It is a generic protocol layered on 45 the 46 distributed computing environment (DCE) RPC specification and facilitates 47 the 48 construction of task-specific communication protocols through features such 49 as: a platform neutral argument/parameter marshaling format (NDR), the 51 Brown/Kindel page 52 1 54 Internet Draft January, 55 1998 57 ability for objects to support multiple interfaces with a safe, interface- 58 level versioning scheme suited to independent evolution by multiple parties, 59 the ability to make authenticated connections and to choose levels of 60 channel 61 security, and a transport-neutral data representation for references 62 (including by-value) to objects. 64 Internet Draft January, 65 1998 67 Table of Contents 69 Status of this Memo...................................1 71 Abstract..............................................1 73 Table of Contents.....................................3 75 1. Introduction.......................................5 77 1.1 Purpose......................................5 79 2. Overall Operation..................................6 81 2.1 Object Calls.................................6 82 2.2 OXIDs and Object Exporters...................7 83 2.3 Class Activation.............................8 84 2.4 Marshaled Interface References...............9 85 2.5 Reference Counting..........................10 86 2.6 Pinging.....................................10 87 2.7 QueryInterface..............................13 88 2.8 Causality ID................................13 90 3. Data Types and Structures.........................13 92 3.1 DCE Packet Headers..........................14 93 3.2 ORPC Base Definitions.......................14 94 3.3 OBJREF......................................20 95 3.4 STDOBJREF...................................22 96 3.5 SORFLAGS....................................23 97 3.6 ORPCINFOFLAGS...............................23 98 3.7 ORPCTHIS....................................24 99 3.8 ORPCTHAT....................................26 100 3.9 HRESULTs....................................26 101 3.10 Body Extensions............................27 103 4. IRemUnknown and IRemUnknown2 interfaces...........28 105 4.1 IRemUnknown::RemQueryInterface..............30 106 4.2 IRemUnknown2::RemQueryInterface2............31 107 4.3 IRemUnknown::RemAddRef......................32 108 4.4 IRemUnknown::RemRelease.....................34 110 5. The OXID Resolver.................................35 112 5.1 OXID Resolver Ports/Endpoints...............35 113 5.2 The IOXIDResolver Interface.................36 115 6. Object Activation.................................46 117 6.1 IRemoteActivation Ports/Endpoints...........46 119 Internet Draft January, 120 1998 122 6.2 The IRemoteActivation Interface.............47 124 7. Security Considerations...........................50 126 8. Acknowledgements..................................50 128 9. References........................................50 130 10. Author's Addresses...............................51 132 Internet Draft January, 133 1998 135 1. Introduction 137 The Distributed Component Object Model protocol (DCOM) is an application- 138 level protocol for object-oriented remote procedure calls and is thus also 139 called "Object RPC" or ORPC. The protocol consists of a set of extensions, 140 layered on the distributed computing environment (DCE) RPC specification 141 [CAE 142 RPC], with which familiarity is assumed. Familiarity is also assumed with 143 the 144 COM (Component Object Model) specification [COM]. 146 Object RPC specifies: 148 @ How calls are made on an object 150 @ How object references are represented, communicated, and maintained 152 1.1 Purpose 154 There is a natural tendency in a networked environment to create entirely 155 new 156 application-level protocols as each new or seemingly unique combination of 157 client, user agent, and server requirement arises. 159 While in many situations the definition of a new protocol is useful and 160 justifiable, there are numerous features which have eventually been added to 161 or required from each new protocol (or which become layered above them) as 162 they evolve and become used in broader contexts. 164 A design goal of the DCOM protocol is the inherent support of standard 165 features required by any distributed application communication protocol. In 166 other words, to act as a framework to facilitate the construction of task- 167 specific communication paths between distributed applications. 169 Data Marshaling 171 A common occurrence among user agents using the HTTP protocol today is the 172 use of complex, task-specific Query URL syntax and HTTP POSTs. Also 173 increasingly common is the POSTing and response with custom MIME types to 174 and 175 from resources which interpret the format and reply in same. While workable, 176 there are drawbacks to this approach including increased complexity and work 177 to produce and consume each new (and unique) format in the client and 178 server, 179 lessened ability to build task-specific firewalls for administration and 180 security purposes, and in many cases definition of platform-centric formats. 182 DCOM utilizes the Network Data Representation (NDR) for arbitrary data types 183 supported by DCE RPC. 185 Security 187 Internet Draft January, 188 1998 190 DCOM leverages the authentication, authorization, and message integrity 191 capabilities of DCE RPC. An implementation may support any level of DCE RPC 192 security. Any connection or call can be made as secure or as insecure as 193 negotiated by the client and the server. 195 Safe Non-Coordinated Versioning of Interfaces 197 In DCOM versioning of interfaces is done through identifiers which are 198 universally unique (UUID's). To version a published interface, a new 199 interface is defined with a different UUID to the updated specification. 200 Multiple parties can simultaneously introduce "revisions" to interfaces by 201 defining related but distinct interfaces without fear of colliding with each 202 other's version numbers and without fear of breaking each other's down-level 203 or up-level clients. 205 To date, the bulk of task-specific protocols (such as custom POSTs or MIME 206 types using HTTP) have little or no concept of versioning at all, and simply 207 "narrow" the incompatibility window by updating clients (typically pages 208 which are being downloaded anyway) and servers (CGI scripts or other HTTP 209 server infrastructure) simultaneously. 211 2. Overall Operation 213 The Object RPC protocol highly leverages the OSF DCE RPC network protocol 214 (see the reference [CAE RPC]). This leverage occurs at both the 215 specification 216 level and the implementation level: the bulk of the implementation effort 217 involved in implementing the DCOM network protocol is in fact that of 218 implementing the DCE RPC network protocol on which it is built. 220 2.1 Object Calls 222 An actual COM network remote procedure call (hereinafter referred to as "an 223 ORPC") is in fact a true DCE remote procedure call (herein termed "a DCE 224 RPC"), a "Request PDU" conforming to the specification for such calls per 225 [CAE RPC]. 227 In an ORPC, the object ID field of the invocation header as specified in 228 [CAE 229 RPC] contains an "IPID". An IPID is a 128-bit identifier known as an 230 interface pointer identifier which represents a particular interface on a 231 particular object in a particular server. As it is passed in the object ID 232 fields of a DCE RPC, the static type of an IPID is in fact a UUID. However, 233 IPIDs are scoped not globally but rather only relative to the server 234 process 236 Internet Draft January, 237 1998 239 which originally allocated them; IPIDs do not necessarily use the standard 240 UUID allocation algorithm, but rather may use a machine-specific algorithm 241 which can assist with dispatching. 243 In an ORPC, the interface ID field of the RPC header specifies the IID, and 244 arguments are found in the body, as usual. However, when viewed from the DCE 245 RPC perspective an additional first argument is always present that is 246 absent 247 in the corresponding COM interface specification. This argument is of type 248 ORPCTHIS, which is described in Section 3.7. It is placed first in the body 249 of the Request PDU, before the actual arguments of the ORPC. 251 It is specifically legal for an ORPC to attempt a call a method number on a 252 given interface which is beyond the number of methods believed by the server 253 to be in that interface. Such calls should cause a fault. 255 Similarly, in a reply to an ORPC (a DCE RPC "Response PDU"), when viewed 256 from 257 the DCE RPC perspective, an additional first return value is always present 258 that is absent in the corresponding COM interface specification. This 259 argument is of type ORPCTHAT, which is described in Section 3.8. It is 260 placed 261 first in the body of the Response PDU, before the actual return values of 262 the 263 ORPC. 265 An ORPCTHAT may also be present in a "Fault PDU." In the Connectionless (CL) 266 Fault PDU, it is placed four bytes after the 32- bit fault code which 267 normally comprises the entire body of the PDU, thus achieving eight byte 268 alignment for the ORPCTHAT; the intervening padding bytes are presently 269 reserved and must be zero. The PDU body length is of course set to encompass 270 the entire body of the Fault PDU, including the ORPCTHAT. In the Connection- 271 Oriented (CO) Fault PDU, the ORPCTHAT is placed in the standard location 272 allocated for the "stub data." In a Fault PDU of either form that results 273 from an ORPC, if an ORPCTHAT is not present then no other data may be 274 substituted in its here-specified location in the PDU. 276 2.2 OXIDs and Object Exporters 278 Although an IPID from a logical perspective semantically determines the 279 server, object and interface to which a particular call should be directed, 280 it does not by itself indicate the binding information necessary to actually 281 carry out an invocation. 283 The protocol represents this "how-to" communication information in a 64-bit 284 value called an object exporter identifier, otherwise known as an OXID. 285 Conceptually, an OXID can be thought of as an implementation scope for an 286 object, which may be a whole machine, a given process, a thread within that 287 process, or other more esoteric implementation scope, but the exact 288 definition of such scopes has no bearing on the protocol itself. Data 290 Internet Draft January, 291 1998 293 structures in each Object Exporter keep track of the IPIDs exported and 294 imported by that Object Exporter. 296 A given machine at any moment may support several OXIDs; however there is 297 always a unique OXID Resolver service per machine which coordinates the 298 management of all the OXIDs on the machine. The OXID Resolver typically (but 299 not necessarily) resides at well-known ports (or endpoints, depending on 300 your 301 terminology -- one per protocol, of course) on the machine. It supports a 302 DCE 303 RPC interface known as IOXIDResolver, described in Section 5.2. 305 An OXID is used to determine the RPC string bindings that allow calls to 306 reach their target IPID. Before making a call, the calling process must 307 translate an OXID into a set of bindings that the underlying RPC 308 implementation understands. It accomplishes this by maintaining a cache of 309 these mappings. When the destination application receives an object 310 reference, it checks to see if it recognizes the OXID. If it does not, then 311 it asks the OXID Resolver which scopes the OXID specified in the object 312 reference for the translation, and saves the resulting set of string 313 bindings in a local table that maps OXIDs to string bindings. 315 Associated with each OXID (ie each Object Exporter) is COM object termed an 316 "OXID object." OXID objects implement (at least) the IRemUnknown interface, 317 a 318 COM interface through which remote management of reference counts and 319 requests for interfaces are returned. 321 2.3 Class Activation 323 The server-provided DCOM class activation facility provides a way for a 324 client to instantiate a new class object on a host machine, obtain its OXID, 325 and obtain one or more IPIDs for the interfaces that it is interested in 326 communicating through, all in one network round-trip. While it is primarily 327 intended for the creation of new objects, the activation facility is free to 328 return the same OXID and IPIDs for all activation requests of a particular 329 class of object; this gives clients an easy way to access a well-known 330 service without having to have a priori knowledge of a specific object (i.e. 331 OXID & IPID) on the host, knowledge which can be invalidated by a reboot or 332 a 333 network failure. 335 Clients are expected to know beforehand either the CLSID or a file moniker 336 which will result in the creation of the class object that they are 337 interested in communicating with. Clients also have the option of providing 338 a 339 client-side IStorage object which will be used to instantiate and initialize 340 the server-side object. 342 Internet Draft January, 343 1998 345 2.4 Marshaled Interface References 347 The DCOM protocol extends the Network Data Representation (NDR) standard 348 specified in [CAE RPC] by defining what can be thought of as a new primitive 349 data type that can be marshaled: that of an interface reference to an 350 object. 351 This is the only extension to NDR made by the DCOM protocol. 353 A marshaled interface reference is described by a type known as an OBJREF, 354 which is described in detail in Section 3.3. An OBJREF in actuality has 355 several variations: 357 NULL 359 This is a reference to no object. 361 STANDARD 363 A standard remote reference. Known as a STDOBJREF. A STDOBJREF contains: 365 @ An IPID, which uniquely specifies the interface and object. 367 @ An object ID (OID), which uniquely specifies the identity of the object on 368 which the IPID is found (scoped to the object exporter with which the 369 object is associated). 371 @ An OXID, which identifies the scope where the implementation of the object 372 is active, and can be used to reach the interface pointer. 374 @ A reference count, indicating the number of references to this IPID that 375 are conveyed by this marshaling. This count, though typically a value of 376 one, may in fact be zero, one, or more (see the next section). 378 @ Some flags, explained later. 380 CUSTOM 382 Contains a class ID (CLSID) and class-specific information. 384 The Custom format gives an object control over the representation of 385 references to itself. For example, an immutable object might be passed by 386 value, in which case the class-specific information would contain the 387 object's immutable data. 389 HANDLER 391 A sub-case of the custom reference in which the class- specific information 392 is standardized. 394 Internet Draft January, 395 1998 397 For example, an object wishes to be represented in client address spaces by 398 a 399 proxy object that caches state. In this case, the class-specific information 400 is just a standard reference to an interface pointer that the handler (proxy 401 object) will use to communicate with the original object. 403 Interface references are always marshaled in little-endian byte order, 404 irrespective of the byte order prevailing in the remainder of the data being 405 marshaled. 407 2.5 Reference Counting 409 In the DCOM protocol, remote reference counting is conducted per interface 410 (per IPID). 412 The actual increment and decrement calls are carried out using 413 (respectively) 414 the RemAddRef and RemRelease methods in a COM interface known as IRemUnknown 415 found on the OXID object associated with each OXID, the IPID of which is 416 returned from the function IOXIDResolver::ResolveOxid (section 5.2.1) or 417 IRemoteActivation::RemoteActivation (section 6.2.1). In contrast to their 418 analogues in IUnknown, RemAddRef and RemRelease can in one call increment or 419 decrement the reference count of many different IPIDs by an arbitrary 420 amount; 421 this allows for greater network efficiency. In the interests of performance, 422 client COM implementations typically do not immediately translate each local 423 AddRef and Release into a remote RemAddRef and RemRelease. Rather, the 424 actual 425 remote release of all interfaces on an object is typically deferred until 426 all 427 local references to all interfaces on that object have been released. 428 Further, one actual remote reference count may be used to service many local 429 reference counts; that is, the client infrastructure may multiplex zero or 430 more local references to an interface into zero or one remote references on 431 the actual IPID. 433 To prevent a malicious application from calling RemRelease incorrectly, an 434 application may request secure references. In that case the application 435 must 436 call RemAddRef (and RemRelease later on) securely and must request private 437 references. Private references are stored by client identity so one client 438 cannot release another client�s references. DCOM requires that each client 439 make a call to get his own secure references, rather then receiving a secure 440 reference from someone who already has one. This reduces the efficiency of 441 interface marshalling because the client must make a callback. 443 2.6 Pinging 445 The above reference counting scheme would be entirely adequate on its own if 446 clients never terminated abnormally, but in fact they do, and the system 448 Brown/Kindel page 449 10 451 Internet Draft January, 452 1998 454 needs to be robust in the face of clients terminating abnormally when they 455 hold remote references. In a DCE RPC, one typically addresses this issue 456 through the use of context handles. Context handles are not used, however, 457 by 458 the DCOM protocol, for reasons of expense. The basic underlying technology 459 used in virtually all protocols for detecting remote abnormal termination is 460 that of periodic pings. Naive use of RPC context handles would result in per 461 object per client process pings being sent to the server. The DCOM protocol 462 includes a pinging infrastructure to significantly reduce network traffic by 463 relying on the client OXID Resolver implementation to do local management of 464 client liveness detection, and having the actual pings be sent only on a 465 machine by machine basis. 467 Pinging is carried out on a per-object (per OID), not a per- interface (per- 468 IPID) basis. Architecturally, at its server machine, each exported object 469 (each exported OID) has associated with it a pingPeriod time value and a 470 numPingsToTimeOut count which together (through their product) determine the 471 overall amount of time known as the "ping period" that must elapse without 472 receiving a ping on that OID before all the remote references to IPIDs 473 associated with that OID can be considered to have expired. Once expiration 474 has occurred, the interfaces behind the IPIDs can, as would be expected, be 475 reclaimed solely on the basis of local knowledge, though the timeliness with 476 which this is carried out, if at all, is implementation specific detail of 477 the server. If the server COM infrastructure defers such garbage collection 478 in this situation (perhaps because it has local references keeping the 479 interface pointer alive) and it later hears a ping, then it knows a network 480 partition healed. It can consider the extant remote references to be 481 reactivated and can continue remote operations. 483 When interface pointers are conveyed from one client to another, such as 484 being passed as either [in] or [out] parameters to a call, the interface 485 pointer is marshaled in one client and unmarshaled in the other. In order to 486 successfully unmarshal the interface, the destination client must obtain at 487 least one reference count on the interface. This is usually accomplished by 488 passing in the marshaled interface STDOBJREF a cPublicRefs of (at least) 489 one; 490 the destination client then takes ownership of that many (more) reference 491 counts to the indicated IPID, and the source client then owns that many 492 fewer 493 reference counts on the IPID. It is legal, however, for zero reference 494 counts 495 to be passed in the STDOBJREF; here, the destination client must (if it does 496 not already have access to that IPID and thus have a non-zero reference 497 count 498 for it) before it successfully unmarshals the interface reference 499 (concretely, e.g., before CoUnmarshalInterface returns) call to the object 500 exporter using IRemUnknown::RemAddRef to obtain a reference count for it. If 501 the destination client is in fact the object's server, then special 503 Brown/Kindel page 504 11 506 Internet Draft January, 507 1998 509 processing is required by the destination client. The remote reference 510 counts 511 being passed to it should, in effect, be "taken out of circulation," as what 512 where heretofore remote references are being converted into local 513 references. 514 Thus, the reference counts present in the STDOBJREF are in fact decremented 515 from the remote reference count for the IPID in question. 517 Some objects have a usage model such that they do not need to be pinged at 518 all; such objects are indicated by the presence of a flag in a STDOBJREF to 519 an interface on the object. Objects which are not pinged in fact need not be 520 reference counted either, though it is legal (but pointless) for a client to 521 reference count the IPIDs of such objects. 523 For all other objects, assuming a non-zero ping period, it is the 524 responsibility of the holder of an interface reference on some object to 525 ensure that pings reach the server frequently enough to prevent expiration 526 of 527 the object. The frequency used by a client depends on the ping period, the 528 reliability of the channel between the client and the server, and the 529 probability of failure (no pings getting through and possible premature 530 garbage-collection) that the client is willing to tolerate. The ping packet 531 and / or its reply may both request changes to the ping period. Through this 532 mechanism, network traffic may be reduced in the face of slow links to busy 533 servers. 535 2.6.1 Delta Pinging 537 Without any further refinements, ping messages could be quite hefty. If 538 machine A held 1024 remote object references (OIDs) on machine B, then it 539 would send 16K byte ping messages. This would be annoying if the set of 540 remote objects was relatively stable and the ping messages were the same 541 from 542 ping to ping. 544 The delta mechanism reduces the size of ping messages. It uses a ping-set 545 interface that allows the pinging of a single set to replace the pinging of 546 multiple OIDs. 548 Instead of pinging each OID, the client defines a set. Each ping contains 549 only the set id and the list of additions and subtractions to the set. 550 Objects that come and go within one ping period are removed from the set 551 without ever having been added. 553 The pinging protocol is carried out using two methods in the (DCE RPC) 554 interface IOXIDResolver on the OXID Resolver: ComplexPing, and SimplePing. 555 ComplexPing is used by clients to group the set of OIDs that they must ping 556 into sets known to the server. These entire sets of OIDs can then be 557 subsequently pinged with a single, short, call to SimplePing. 559 Brown/Kindel page 560 12 562 Internet Draft January, 563 1998 565 2.7 QueryInterface 567 zThe IRemUnknown interface on the OXID object, in addition to servicing 568 reference counting as described above also services QueryInterface calls for 569 remote clients for IPIDs managed by that object exporter. 570 IRemUnknown::RemQueryInterface differs from IUnknown::QueryInterface in much 571 the same way as RemAddRef and RemRelease differ from AddRef and Release, in 572 that it is optimized for network access by being able to retrieve many 573 interfaces at once. 575 2.8 Causality ID 577 Each ORPC carries with it a UUID known as the causality id that connects 578 together the chain of ORPC calls that are causally related. If an outgoing 579 ORPC is made while servicing an incoming ORPC, the outgoing call is to have 580 the same causality id as the incoming call. If an outgoing ORPC is made 581 while 582 not servicing an incoming ORPC, then a new causality id is allocated for it. 584 Causality ids may in theory be reused as soon as it is certain that no 585 transitively outstanding call is still in progress which uses that call. In 586 practice, however, in the face of transitive calls and the possibility of 587 network failures in the middle of such call chains, it is difficult to know 588 for certain when this occurs. Thus, pragmatically, causality ids are not 589 reusable. 591 The causality id can be used by servers to understand when blocking or 592 deferring an incoming call (supported in some COM server programming models) 593 is very highly probable to cause a deadlock, and thus should be avoided. 595 The causality id for maybe, idempotent, and broadcast calls must be set to 596 null (e.g., all zeros). If a server makes a ORPC call while processing such 597 a 598 call, a new causality id must be generated as if it were a top level call. 600 3. Data Types and Structures 602 This following several sections present the technical details of the DCOM 603 protocol. 605 Brown/Kindel page 606 13 608 Internet Draft January, 609 1998 611 3.1 DCE Packet Headers 613 Object RPC sits entirely on top of DCE RPC. The following list describes the 614 elements of ORPC that are specified above and beyond DCE RPC. 616 @ The object id field of the header must contain the IPID. 618 @ The interface id of the RPC header must contain the IID, even though it is 619 not needed given the IPID. This allows ORPC to sit on top of DCE RPC. An 620 unmodified DCE RPC implementation will correctly dispatch based on IID and 621 IPID. An optimized RPC need only dispatch based on IPID. 623 @ An IPID uniquely identifies a particular interface on a particular object 624 on a machine. The converse is not true; a particular interface on a 625 particular object may be represented by multiple IPIDs. IPIDs are unique 626 on 627 their OXID. IPIDs may be reused, however reuse of IPIDs should be avoided. 629 @ Datagram, maybe, and idempotent calls are all allowed in ORPC. 631 @ Interface pointers may not be passed on maybe or idempotent calls. 633 @ Datagram broadcasts are not allowed in ORPC. 635 @ Faults are returned in the stub fault field of the DCE RPC fault packet. 636 Any 32 bit value may be returned. Only RPC_E_VERSION_MISMATCH is pre- 637 specified. 639 @ DCE RPC cancel is supported. 641 @ All interface version numbers must be 0.0. 643 @ The transfer syntax GUID is {8a885d04-1ceb-11c9-9fe8-08002b104860}, 644 version 645 2 (0x02). 647 3.2 ORPC Base Definitions 649 There are several fundamental data types and structures on which the COM 650 network protocol is built. These types are shown here in standard C header 651 format. 653 [ 654 uuid(99fcfe60-5260-101b-bbcb-00aa0021347a), 655 pointer_default(unique) 656 ] 658 Brown/Kindel page 659 14 661 Internet Draft January, 662 1998 664 interface ObjectRpcBaseTypes 665 { 666 //////////////////////////////////////////////////////////// 667 // 668 // Identifier Definitions 669 // 670 //////////////////////////////////////////////////////////// 672 typedef unsigned hyper ID; 673 typedef ID MID; // Machine Identifier 674 typedef ID OXID; // Object Exporter Identifier 675 typedef ID OID; // Object Identifer 676 typedef ID SETID; // Ping Set Identifier 677 typedef GUID IPID; // Interface Pointer Identifier 678 typedef GUID CID; // Causality Identifier 680 typedef const IPID &REFIPID; 681 typedef REFGUID REFIPID; 683 ////////////////////////////////////////////////////////////////// 684 // 685 // ORPC Call Packet Format 686 // 687 ////////////////////////////////////////////////////////////////// 689 // COM_MINOR_VERSION = 1 (NT4.0, SP1, SP2, DCOM95). 690 // - Initial Release 691 // - Must be used when talking to downlevel machines, including 692 // on Remote Activation calls. 693 // COM_MINOR_VERSION = 2 (NT4.0 SP3 and beyond). 694 // - Added ResolveOxid2 to IObjectExporter to retrieve the 695 // COM version number of the server. Passed to the NDR engine 696 // to fix fatal endian-ness flaw in the way OLEAUTOMATION 697 marshals 698 // BSTRS. Previous way used trailing padding, which is not NDR 699 // compatible. See Bug# 69189. 700 // COM_MINOR_VERSION = 3 (NT4.0 SP4 and DCOM95 builds 1018 and beyond) 701 // - OLEAUT32 added two new types to the SAFEARRAY, but SAFEARRAY 702 // previously included the "default" keyword, which prevented 703 // downlevel NDR engines from correctly handling any extensions. 704 // Machines with version >=5.3 don't use "default" and will 705 // gracefully handle future extensions to SAFEARRAY. 707 // old constants (for convenience) 708 const unsigned short COM_MINOR_VERSION_1 = 1; 709 const unsigned short COM_MINOR_VERSION_2 = 2; 711 Brown/Kindel page 712 15 714 Internet Draft January, 715 1998 717 // current version 718 const unsigned short COM_MAJOR_VERSION = 5; 719 const unsigned short COM_MINOR_VERSION = 3; 721 // Component Object Model version number 722 typedef struct tagCOMVERSION 723 { 724 unsigned short MajorVersion; // Major version number 725 unsigned short MinorVersion; // Minor version number 726 } COMVERSION; 728 // enumeration of additional information present in the call packet. 729 // Should be an enum but DCE IDL does not support sparse enumerators. 731 const unsigned long ORPCF_NULL = 0; // no additional info in 732 packet 733 const unsigned long ORPCF_LOCAL = 1; // call is local to this 734 machine 735 const unsigned long ORPCF_RESERVED1 = 2; // reserved for local use 736 const unsigned long ORPCF_RESERVED2 = 4; // reserved for local use 737 const unsigned long ORPCF_RESERVED3 = 8; // reserved for local use 738 const unsigned long ORPCF_RESERVED4 = 16; // reserved for local use 740 // Extension to implicit parameters. 741 typedef struct tagORPC_EXTENT 742 { 743 GUID id; // Extension identifier. 744 unsigned long size; // Extension size. 745 [size_is((size+7)&~7)] byte data[]; // Extension data. 746 } ORPC_EXTENT; 748 // Array of extensions. 749 typedef struct tagORPC_EXTENT_ARRAY 750 { 751 unsigned long size; // Num extents. 752 unsigned long reserved; // Must be zero. 753 [size_is((size+1)&~1,), unique] ORPC_EXTENT **extent; // extents 754 } ORPC_EXTENT_ARRAY; 756 // implicit 'this' pointer which is the first [in] parameter on 758 Brown/Kindel page 759 16 761 Internet Draft January, 762 1998 764 // every ORPC call. 765 typedef struct tagORPCTHIS 766 { 767 COMVERSION version; // COM version number 768 unsigned long flags; // ORPCF flags for presence of other 769 data 770 unsigned long reserved1; // set to zero 771 CID cid; // causality id of caller 773 // Extensions. 774 [unique] ORPC_EXTENT_ARRAY *extensions; 775 } ORPCTHIS; 777 // implicit 'that' pointer which is the first [out] parameter on 778 // every ORPC call. 779 typedef struct tagORPCTHAT 780 { 781 unsigned long flags; // ORPCF flags for presence of other 782 data 784 // Extensions. 785 [unique] ORPC_EXTENT_ARRAY *extensions; 786 } ORPCTHAT; 788 ////////////////////////////////////////////////////////////////// 789 // 790 // Marshaled COM Interface Wire Format 791 // 792 ////////////////////////////////////////////////////////////////// 794 // DUALSTRINGARRAYS are the return type for arrays of network addresses, 795 // arrays of endpoints and arrays of both used in many ORPC interfaces 797 const unsigned short NCADG_IP_UDP = 0x08; 798 const unsigned short NCACN_IP_TCP = 0x07; 799 const unsigned short NCADG_IPX = 0x0E; 800 const unsigned short NCACN_SPX = 0x0C; 801 const unsigned short NCACN_NB_NB = 0x12; 802 const unsigned short NCACN_NB_IPX = 0x0D; 803 const unsigned short NCACN_DNET_NSP = 0x04; 804 const unsigned short NCACN_HTTP = 0xlF; 806 Brown/Kindel page 807 17 809 Internet Draft January, 810 1998 812 typedef struct tagSTRINGBINDING 813 { 814 unsigned short wTowerId; // Cannot be zero. 815 unsigned short aNetworkAddr; // Zero terminated. 816 } STRINGBINDING; 818 const unsigned short COM_C_AUTHZ_NONE = 0xffff; 820 typedef struct tagSECURITYBINDING 821 { 822 unsigned short wAuthnSvc; // Cannot be zero. 823 unsigned short wAuthzSvc; // Must not be zero. 824 unsigned short aPrincName; // Zero terminated. 825 } SECURITYBINDING; 827 typedef struct tagDUALSTRINGARRAY 828 { 829 unsigned short wNumEntries; // Number of entries in array. 830 unsigned short wSecurityOffset; // Offset of security info. 832 // The array contains two parts, a set of STRINGBINDINGs 833 // and a set of SECURITYBINDINGs. Each set is terminated by an 834 // extra zero. The shortest array contains four zeros. 836 [size_is(wNumEntries)] unsigned short aStringArray[]; 837 } DUALSTRINGARRAY; 839 // signature value for OBJREF (object reference, actually the 840 // marshaled form of a COM interface). 841 const unsigned long OBJREF_SIGNATURE = 0x574f454d; // 'MEOW' 843 // flag values for OBJREF 844 const unsigned long OBJREF_STANDARD = 0x1; // standard marshaled objref 845 const unsigned long OBJREF_HANDLER = 0x2; // handler marshaled objref 846 const unsigned long OBJREF_CUSTOM = 0x4; // custom marshaled objref 848 // Flag values for a STDOBJREF (standard part of an OBJREF). 849 // SORF_OXRES1 - SORF_OXRES8 are reserved for the object exporters 850 // use only, object importers must ignore them and must not enforce MBZ. 852 const unsigned long SORF_OXRES1 = 0x1; // reserved for exporter 853 const unsigned long SORF_OXRES2 = 0x20; // reserved for exporter 855 Brown/Kindel page 856 18 858 Internet Draft January, 859 1998 861 const unsigned long SORF_OXRES3 = 0x40; // reserved for exporter 862 const unsigned long SORF_OXRES4 = 0x80; // reserved for exporter 863 const unsigned long SORF_OXRES5 = 0x100;// reserved for exporter 864 const unsigned long SORF_OXRES6 = 0x200;// reserved for exporter 865 const unsigned long SORF_OXRES7 = 0x400;// reserved for exporter 866 const unsigned long SORF_OXRES8 = 0x800;// reserved for exporter 868 const unsigned long SORF_NULL = 0x0; // convenient for 869 initializing SORF 870 const unsigned long SORF_NOPING = 0x1000;// Pinging is not required 872 // standard object reference 873 typedef struct tagSTDOBJREF 874 { 875 unsigned long flags; // STDOBJREF flags (see above) 876 unsigned long cPublicRefs; // count of references passed 877 OXID oxid; // oxid of server with this oid 878 OID oid; // oid of object with this ipid 879 IPID ipid; // ipid of Interface 880 } STDOBJREF; 882 // OBJREF is the format of a marshaled interface pointer. 883 typedef struct tagOBJREF 884 { 885 unsigned long signature; // must be OBJREF_SIGNATURE 886 unsigned long flags; // OBJREF flags (see above) 887 GUID iid; // interface identifier 889 [switch_is(flags), switch_type(unsigned long)] union 890 { 891 [case(OBJREF_STANDARD)] struct 892 { 893 STDOBJREF std; // standard objref 894 DUALSTRINGARRAY saResAddr; // resolver address 895 } u_standard; 897 [case(OBJREF_HANDLER)] struct 898 { 899 STDOBJREF std; // standard objref 900 CLSID clsid; // Clsid of handler code 901 DUALSTRINGARRAY saResAddr; // resolver address 903 Brown/Kindel page 904 19 906 Internet Draft January, 907 1998 909 } u_handler; 911 [case(OBJREF_CUSTOM)] struct 912 { 913 CLSID clsid; // Clsid of unmarshaling code 914 unsigned long cbExtension;// size of extension data 915 unsigned long size; // size of data that follows 916 [size_is(size), ref] byte *pData; // extension + class 917 specific data 918 } u_custom; 920 } u_objref; 922 } OBJREF; 924 // wire representation of a marshalled interface pointer 925 typedef struct tagMInterfacePointer 926 { 927 ULONG ulCntData; // size of data 928 [size_is(ulCntData)] BYTE abData[]; // data (OBJREF) 929 } MInterfacePointer; 931 typedef [unique] MInterfacePointer * PMInterfacePointer; 932 } 934 ////////////////////////////////////////////////////////////////// 936 3.3 OBJREF 938 An OBJREF is the data type used to represent an actual marshaled object 939 reference. An OBJREF can either be empty or assume one of three variations, 940 depending on the degree to which the object being marshaled uses the hook 941 architecture (IMarshal, etc.) in the marshaling infrastructure. The OBJREF 942 structure is a union consisting of a switch flag followed by the appropriate 943 data. 945 3.3.1 OBJREF_STANDARD 947 Contains one interface of an object marshaled in standard form. Contains a 948 standard reference, along with a set of protocol sequences and network 950 Brown/Kindel page 951 20 953 Internet Draft January, 954 1998 956 addresses that can be used to bind to an OXID resolver that is able to 957 resolve the OXID in the STDOBJREF. This is useful when marshaling a proxy to 958 give to another machine (a.k.a. the "middleman" case). The marshaling 959 machine 960 specifies the saResAddr for the OXID Resolver on the server machine, 961 eliminating the need for the unmarshaler to call the marshaler (middleman) 962 back to get this information. Further, the marshaler does not need to keep 963 the OXID in its cache beyond the lifetime of its own references in order to 964 satisfy requests from parties that it just gave the OBJREF to. 966 Member Type Semantic 968 signature unsigned long Must be OBJREF_SIGNATURE 969 flags unsigned long OBJREF flags (section 3.5) 970 iid GUID Interface identifier 971 std STDOBJREF A standard object reference used to connect to 972 the source object (Section 3.4). 973 saResAddr STRINGARRAY The resolver address. 975 3.3.2 OBJREF_HANDLER 977 A marshaling of an object that wishes to use handler marshaling. For 978 example, 979 an object wishes to be represented in client address spaces by a proxy 980 object 981 that caches state. In this case, the class- specific information is just a 982 standard reference to an interface pointer that the handler (proxy object) 983 will use to communicate with the original object. See the IStdMarshalInfo 984 interface. 986 Member Type Semantic 988 signature unsigned long Must be OBJREF_SIGNATURE 989 flags unsigned long OBJREF flags (section 3.5) 990 iid GUID Interface identifier 991 std STDOBJREF A standard object reference used to connect to 992 the source object (Section 3.4). 993 clsid CLSID The CLSID of handler to create in the 994 destination client. 995 saResAddr STRINGARRAY The resolver address. 997 Brown/Kindel page 998 21 1000 Internet Draft January, 1001 1998 1003 3.3.3 OBJREF_CUSTOM 1005 A marshaling of an object which supports custom marshaling. The Custom 1006 format 1007 gives an object control over the representation of references to itself. For 1008 example, an immutable object might be passed by value, in which case the 1009 class-specific information would contain the object's immutable data. See 1010 the 1011 IMarshal interface. 1013 Member Type Semantic 1015 signature unsigned long Must be OBJREF_SIGNATURE 1016 flags unsigned long OBJREF flags (section 3.5) 1017 GUID iid Interface identifier 1018 clsid CLSID The CLSID of the object to create in the 1019 destination client. 1020 cbExtension unsigned long The size of the extension data. 1021 size unsigned long The size of the marshaled data provided by the 1022 source object, plus the size of the extension 1023 data, and passed in pData. 1024 pData byte* The data bytes that should be passed to 1025 IMarshal::UnmarshalInterface on a new instance 1026 of class clsid in order to initialize it and 1027 complete the unmarshal process (class specific 1028 data). 1029 The first cbExtension bytes are the reserved 1030 for future extensions to the protocol, and 1031 should not be passed into the custom 1032 unmarshaler. CoUnmarshalInterface should skip 1033 the extension data, and the data starting at 1034 pData+cbExtension should be given to the custom 1035 unmarshaler. 1037 3.4 STDOBJREF 1039 An instance of a STDOBJREF represents a COM interface pointer that has been 1040 marshaled using the standard COM network protocol. 1042 The members and semantics of the STDOBJREF structure are as follows: 1044 Member Semantic 1046 flags Flag values taken from the enumeration SORFFLAGS. These are 1047 described in Section 3.5. 1049 Brown/Kindel page 1050 22 1052 Internet Draft January, 1053 1998 1055 cPublicRefs The number of reference counts on ipid that are being 1056 transferred in this marshaling. 1057 oxid The OXID of the server that owns this OID. 1058 oid The OID of the object to which ipid corresponds. 1059 ipid The IPID of the interface being marshaled. 1061 3.5 SORFLAGS 1063 The various SORFLAGS values have the following meanings. The SORF_OXRESxxx 1064 bit flags are reserved for the object exporter's use only, and must be 1065 ignored by object importers. They need not be passed through when marshaling 1066 an interface proxy. 1068 Flag Meaning 1070 SORF_NULL Convenient for initialization. 1071 SORF_OXRES1 Reserved for exporter. 1072 SORF_OXRES2 Reserved for exporter. 1073 SORF_OXRES3 Reserved for exporter. 1074 SORF_OXRES4 Reserved for exporter. 1075 SORF_OXRES5 Reserved for exporter. 1076 SORF_OXRES6 Reserved for exporter. 1077 SORF_OXRES7 Reserved for exporter. 1078 SORF_OXRES8 Reserved for exporter. 1079 SORF_NOPING This OID does not require pinging. Further, all 1080 interfaces on this OID, including this IPID, need not be 1081 reference counted. Pinging and reference counting on 1082 this object and its interfaces are still permitted, 1083 however, though such action is pointless. 1085 3.6 ORPCINFOFLAGS 1087 The various ORPCINFOFLAGS have the following meanings. 1089 Flag Meaning 1091 ORPCF_NULL (Not a real flag. Merely a defined constant indicating the 1092 absence of any flag values.) 1093 ORPCF_LOCAL The destination of this call is on the same machine on 1094 which 1095 it originates. This value is never to be specified in calls 1096 which are not in fact local. 1098 Brown/Kindel page 1099 23 1101 Internet Draft January, 1102 1998 1104 ORPCF_RESERVED1 If ORPCF_LOCAL is set, then reserved for local use; 1105 otherwise, reserved for future use. 1106 ORPCF_RESERVED2 If ORPCF_LOCAL is set, then reserved for local use; 1107 otherwise, reserved for future use. 1108 ORPCF_RESERVED3 If ORPCF_LOCAL is set, then reserved for local use; 1109 otherwise, reserved for future use. 1110 ORPCF_RESERVED4 If ORPCF_LOCAL is set, then reserved for local use; 1111 otherwise, reserved for future use. 1113 Implementations may use the local and reserved flags to indicate any extra 1114 information needed for local calls. Note that if the ORPCF_LOCAL bit is not 1115 set and any of the other bits are set then the receiver should return a 1116 fault. 1118 3.7 ORPCTHIS 1120 In every Request PDU that is an ORPC, the body (CL case) or the stub data 1121 (CO 1122 case) which normally contains the marshaled arguments in fact begins with an 1123 instance of the ORPCTHIS structure. The marshaled arguments of the COM 1124 interface invocation follow the ORPCTHIS; thus, viewed at the DCE RPC 1125 perspective, the call has an additional first argument. The ORPCTHIS is 1126 padded with zero-bytes if necessary to achieve an overall size that is a 1127 multiple of eight bytes; thus, the remaining arguments are as a whole eight 1128 byte aligned. 1130 As in regular calls, the causality id must be propagated. If A calls 1131 ComputePi on B, B calls Release on C (which gets converted to RemRelease), 1132 and C calls Add on A, A will see the same causality id that it called B 1133 with. 1135 Member Type Semantic 1137 version COMVERSION The version number of the COM protocol used 1138 to make this particular ORPC. The initial 1139 value will be 5.1. Each packet contains the 1140 sender's major and minor ORPC version 1141 numbers. The client's and server's major 1142 versions must be equal. Backward compatible 1143 changes in the protocol are indicated by 1144 higher minor version numbers. Therefore, a 1145 server's minor version must be greater than 1146 or equal to the client's. However, if the 1147 server's minor version exceeds the client's 1149 Brown/Kindel page 1150 24 1152 Internet Draft January, 1153 1998 1155 minor version, it must return the client's 1156 minor version and restrict its use of the 1157 protocol to the minor version specified by 1158 the client. A protocol version mismatch 1159 causes the RPC_E_VERSION_MISMATCH ORPC 1160 fault 1161 to be returned. 1162 flags unsigned long Flag values taken from the enumeration 1163 ORPCINFOFLAGS (section 3.6). Reserved 1164 unsigned long Must be set to zero. 1165 reserved1 unsigned long Set to zero. 1166 cid CID The causality id of this ORPC. 1167 extensions ORPC_EXTENT_ARRAY* The body extensions, if any, passed with 1168 this call. Body extensions are GUID-tagged 1169 blobs of data which are marshaled as an 1170 array of bytes. Extensions are always 1171 marshaled with initial eight byte 1172 alignment. 1173 Body extensions which are presently defined 1174 are described in Section 3.10. 1176 The cid field contains the causality id. Each time a client makes a unique 1177 call, a new causality id is generated. If a server makes a call while 1178 processing a request from a client, the new call must have the same 1179 causality 1180 id as the call currently being processed. This allows simple servers to 1181 avoid 1182 working on more then one thing at a time (for example A calls B calls A 1183 again, meanwhile C tries to call A with a new causality id). It tells the 1184 server that he is being called because he asked someone to do something for 1185 him. There are several interesting exceptions. 1187 The causality id for maybe and idempotent calls must be set to CID_NULL. If 1188 a 1189 server makes a ORPC call while processing such a call, a new causality id 1190 must be generated. 1192 In the face of network failures, the same causality id may end up in use by 1193 two independent processes at the same time. If A calls B calls C calls D and 1194 C fails, both B and D can independently, simultaneously make calls to E with 1195 the same causality id. 1197 The extensions field contains extensions to the channel header, described in 1198 Section 3.10. Note that in order to force the ORPCTHIS header to be 8 byte 1199 aligned an even number of extensions must be present and the size of the 1200 extension data must be a multiple of 8. 1202 Brown/Kindel page 1203 25 1205 Internet Draft January, 1206 1998 1208 3.8 ORPCTHAT 1210 In every Response PDU that is an ORPC, the body (CL case) or the stub data 1211 (CO case) which normally contains the marshaled output parameters in fact 1212 begins with an instance of the ORPCTHAT structure. The marshaled output 1213 parameters of the COM interface invocation follow the ORPCTHAT; thus, viewed 1214 at the DCE RPC perspective, the call has an additional output parameters. 1215 The 1216 ORPCTHAT is padded with zero-bytes if necessary to achieve an overall size 1217 that is a multiple of eight bytes; thus, the remaining output parameters as 1218 a 1219 whole are eight byte aligned. 1221 Member Type Semantic 1223 flags unsigned long Flag values taken from the enumeration 1224 ORPCINFOFLAGS (section 3.6). 1225 extensions ORPC_EXTENT_ARRAY* The body extensions, if any, returned by 1226 this call. See Section 3.10 for a general 1227 description of body extensions as well as 1228 a description of existing well-known 1229 extensions. 1231 3.9 HRESULTs 1233 HRESULTs are the 32-bit return value from ORPC methods. The following is a 1234 partial list of already defined HRESULTs. 1236 Value Meaning 1238 S_OK Success. (0x00000000) 1239 E_OUTOFMEMORY Insufficient memory to complete the call. 1240 (0x80000002) 1241 E_INVALIDARG One or more arguments are invalid. (0x80000003) 1242 E_NOINTERFACE No such interface supported (0x80000004) 1243 E_ACCESSDENIED A secured operation has failed due to inadequate 1244 security privileges. (0x80070005) 1245 E_UNEXPECTED Unknown, but relatively catastrophic error. 1246 (0x8000FFFF) 1247 S_FALSE False. (0x00000001) 1248 RPC_S_PROCNUM_OUT_OF_RANGE The procedure number is out of range. 1249 (0xC002002E) 1250 RPC_E_INVALID_OXID The object exporter was not found. (0x80070776) 1251 RPC_E_INVALID_OID The object specified was not found or 1252 recognized. 1254 Brown/Kindel page 1255 26 1257 Internet Draft January, 1258 1998 1260 (0x80070777) 1261 RPC_E_INVALID_SET The object exporter set specified was not found. 1262 (0x80070778) 1263 RPC_E_INVALID_OBJECT The requested object does not exist. 1264 (0x80010114) 1265 RPC_E_VERSION_MISMATCH The version of COM on the client and server 1266 machines does not match. (0x80010110) 1268 Further details TBS. 1270 3.10 Body Extensions 1272 Body Extensions are UUID-tagged blocks of data which are useful for 1273 conveying 1274 additional, typically out-of-band, information on incoming invocations 1275 (within ORPCTHIS, Section 3.7) and in replies (within ORPCTHAT, Section 1276 3.8). 1278 Any implementations of the DCOM protocol may define its own extensions with 1279 their own UUIDs. Implementations should skip over extensions which they do 1280 not recognize or do not wish to support. 1282 Body Extensions are marshaled as an array of bytes with initial eight byte 1283 alignment. The following sections describe several existing body extensions. 1285 3.10.1 Debugging Extension 1287 {f1f19680-4d2a-11ce-a66a-0020af6e72f4} 1289 This extension aids in debugging ORPC. In particular it is designed to allow 1290 single stepping over an ORPC call into the server and out of the server into 1291 the client. 1293 Further details TBS. 1295 3.10.2 Extended Error Extension 1297 {f1f19681-4d2a-11ce-a66a-0020af6e72f4} 1299 The extended error information body extension conveys extended error 1300 information concerning the original root cause of a error back to a caller 1301 so 1302 that the caller can deal with it. This extension is only semantically useful 1303 in Response and Fault PDUs. 1305 It is intended that this error information is suitable for displaying 1306 information to a human being who is the user; this information is not 1308 Brown/Kindel page 1309 27 1311 Internet Draft January, 1312 1998 1314 intended to be the basis for logic decisions in a piece of client code, for 1315 doing so couples the client code to the implementation of the server. 1316 Rather, 1317 client code should act semantically only on the information returned through 1318 the interface that it invokes. 1320 Further details TBS. 1322 4. IRemUnknown and IRemUnknown2 interfaces 1324 The IRemUnknown interface is used by remote clients for manipulating 1325 reference counts on the IPIDs that they hold and for obtaining additional 1326 interfaces on the objects on which those IPIDs are found. 1328 References are kept per interface rather then per object. 1330 This interface is implemented by the COM "OXID object" associated with each 1331 OXID (i.e. each Object Exporter). The IPID for the IRemUnknown interface on 1332 this object is returned from IOXIDResolver::ResolveOxid (see Section 5.2.1), 1333 or when an object is activated with IRemoteActivation::RemoteActivation (see 1334 section 6.2.1). An OXID object need never be pinged; its interfaces (this 1335 IPID included) need never be reference counted. IRemUnknown is specified as 1336 follows: 1338 The IRemUnknown2 interface introduced in version 5.2 of the DCOM protocol 1339 inherits from IRemUnknown and adds an extra method �- RemoteQueryInterface2 1340 � 1341 - which allows clients to retrieve interface pointers to objects which 1342 supply 1343 additional data beyond the STDOBJREF in their marshaled interface packets. 1345 // The remote version of IUnknown. This interface exists on every 1346 // OXID (whether an OXID represents either a thread or a process is 1347 // implementation specific). It is used by clients to query for new 1348 // interfaces, get additional references (for marshaling), and release 1349 // outstanding references. 1350 // This interface is passed along during OXID resolution. 1351 // 1352 [ 1353 object, 1354 uuid(00000131-0000-0000-C000-000000000046) 1355 ] 1356 interface IRemUnknown : IUnknown 1357 { 1358 typedef struct tagREMQIRESULT 1360 Brown/Kindel page 1361 28 1363 Internet Draft January, 1364 1998 1366 { 1367 HRESULT hResult; // result of call 1368 STDOBJREF std; // data for returned interface 1369 } REMQIRESULT; 1371 HRESULT RemQueryInterface 1372 ( 1373 [in] REFIPID ripid, // interface to QI on 1374 [in] unsigned long cRefs, // count of AddRefs requested 1375 [in] unsigned short cIids, // count of IIDs that follow 1376 [in, size_is(cIids)] 1377 IID* iids, // IIDs to QI for 1378 [out, size_is(,cIids)] 1379 REMQIRESULT** ppQIResults // results returned 1380 ); 1382 typedef struct tagREMINTERFACEREF 1383 { 1384 IPID ipid; // ipid to AddRef/Release 1385 unsigned long cPublicRefs; 1386 unsigned long cPrivateRefs; 1387 } REMINTERFACEREF; 1389 HRESULT RemAddRef 1390 ( 1391 [in] unsigned short cInterfaceRefs, 1392 [in, size_is(cInterfaceRefs)] 1393 REMINTERFACEREF InterfaceRefs[], 1394 [out, size_is(cInterfaceRefs)] 1395 HRESULT* pResults 1396 ); 1398 HRESULT RemRelease 1399 ( 1400 [in] unsigned short cInterfaceRefs, 1401 [in, size_is(cInterfaceRefs)] 1402 REMINTERFACEREF InterfaceRefs[] 1403 ); 1404 } 1406 // Derived from IRemUnknown, this interface supports Remote Query interface 1407 // for objects that supply additional data beyond the STDOBJREF in their 1409 Brown/Kindel page 1410 29 1412 Internet Draft January, 1413 1998 1415 // marshaled interface packets. 1417 [ 1418 object, 1419 uuid(00000142-0000-0000-C000-000000000046) 1420 ] 1422 interface IRemUnknown2 : IRemUnknown 1423 { 1424 #ifndef DO_NO_IMPORTS 1425 import "unknwn.idl"; 1426 import "obase.idl"; 1427 #endif 1429 HRESULT RemQueryInterface2 1430 ( 1431 [in] REFIPID ripid, 1432 [in] unsigned short cIids, 1433 [in, size_is(cIids)] IID *iids, 1434 [out, size_is(cIids)] HRESULT *phr, 1435 [out, size_is(cIids)] MInterfacePointer **ppMIF 1436 ); 1437 } 1439 4.1 IRemUnknown::RemQueryInterface 1441 QueryInterface for and return the result thereof for zero or more interfaces 1442 from the interface behind the IPID ipid. ipid must designate an interface 1443 derived from IUnknown (recall that all remoted interfaces must derive from 1444 IUnknown). The QueryInterface calls on the object that are used to service 1445 this request are conducted on the IUnknown interface of the object. 1447 Argument Type Semantic 1449 ripid REFIPID The interface on an object from whom more 1450 interfaces are desired. 1451 cRefs unsigned long The number of references sought on each of 1452 the 1453 returned IIDs. 1454 cIids unsigned short The interfaces being requested. 1455 iids IID* The list of IIDs that name the interfaces 1456 sought on this object. 1457 ppQIResults REMQIRESULT** The place at which the array of the results 1458 of 1459 the various QueryInterface calls are 1460 returned. 1462 Brown/Kindel page 1463 30 1465 Internet Draft January, 1466 1998 1468 ReturnValue Meaning 1470 S_OK Success. An attempt was made to retrieve each of the 1471 requested interfaces from the indicated object; that 1472 is, QueryInterface was actually invoked for each 1473 IID. 1474 QueryInterface returned S_OK for every IID 1475 specified. 1476 S_FALSE Success. An attempt was made to retrieve each of the 1477 requested interfaces from the indicated object; that 1478 is, QueryInterface was actually invoked for each 1479 IID. 1480 QueryInterface returned a failure code for at least 1481 one of the IIDs specified. 1482 E_NOINTERFACE QueryInterface returned a failure code for every IID 1483 specifed. 1484 E_INVALIDARG One or more arguments (likely ipid) were invalid. No 1485 result values are returned. 1486 E_UNEXPECTED An unspecified error occurred. 1487 E_OUTOFMEMORY Insufficient memory to complete the call. 1488 RPC_E_INVALID_OBJECT The requested object does not exist. No result 1489 values 1490 are returned. 1492 4.1.1 REMQIRESULT 1494 The REMQIRESULT structure contains the following members: 1496 Member Type Semantic 1498 hResult HRESULT The result code from the QueryInterface call made 1499 for the requested IID. 1500 std STDOBJREF The data for the returned interface. Note that if 1501 hResult indicates failure then the contents of 1502 STDOBJREF are undefined. 1504 4.2 IRemUnknown2::RemQueryInterface2 1506 Like RemQueryInterface, this method queries for zero or more interfaces from 1507 the interface behind the IPID ipid. Instead of returning the STDOBJREF 1508 marshaled interface packet, this method can return any marshaled data packet 1509 in the form of a blob of bytes (including the traditional STDOBJREF). 1511 Argument Type Semantic 1513 ripid REFIPID The interface on an object from whom more 1515 Brown/Kindel page 1516 31 1518 Internet Draft January, 1519 1998 1521 interfaces are desired. 1522 cIids unsigned short The number of references sought on each of 1523 the returned IIDs. 1524 iids IID* The interfaces being requested. 1525 phr HRESULT* The result code returned from 1526 QueryInterface() on each interface in the 1527 iids array. 1528 ppMIF MinterfacePointer** The marshaled interface packet for each of 1529 the IIDs requested. 1531 ReturnValue Meaning 1533 S_OK Success. An attempt was made to retrieve each of the 1534 requested interfaces from the indicated object; that 1535 is, QueryInterface was actually invoked for each IID. 1536 QueryInterface returned S_OK for every IID specified. 1537 S_FALSE Success. An attempt was made to retrieve each of the 1538 requested interfaces from the indicated object; that 1539 is, QueryInterface was actually invoked for each IID. 1540 QueryInterface returned a failure code for at least 1541 one of the IIDs specified. 1542 E_NOINTERFACE QueryInterface returned a failure code for every IID 1543 specifed. 1544 E_INVALIDARG One or more arguments (likely ipid) were invalid. No 1545 result values are returned. 1546 E_UNEXPECTED An unspecified error occurred. 1547 E_OUTOFMEMORY Insufficient memory to complete the call. 1548 RPC_E_INVALID_OBJECT The requested object does not exist. No result values 1549 are returned. 1551 4.3 IRemUnknown::RemAddRef 1553 Obtain and grant ownership to the caller of one or more reference counts on 1554 one or more IPIDs managed by the corresponding OXID. 1556 Argument Type Semantic 1558 cInterfaceRefs unsigned short The size of the rgRefs array. 1559 InterfaceRefs REMINTERFACEREF[] An array of REMINTERFACEREFs, cRefs 1560 large. Each IPID indicates an interface 1561 managed by this OXID on whom more 1562 reference counts are sought. The 1563 corresponding reference count 1565 Brown/Kindel page 1566 32 1568 Internet Draft January, 1569 1998 1571 (cInterfaceRefs), which may not be zero 1572 (and thus is one or more), indicates the 1573 number of reference counts sought on 1574 that IPID. 1575 pResults HRESULT* An array of HRESULTs cInterfaceRefs 1576 large, each containing the result of 1577 attempting an AddRef on the ipid in the 1578 corresponding REMINTERFACREF. 1580 Return Value Meaning 1582 S_OK Success. An attempt was made to retrieve each of the 1583 requested 1584 interface references. 1585 E_INVALIDARG One or more of the IPIDs indicated were not in fact managed 1586 by 1587 this OXID, or one or more of the requested reference counts 1588 was zero. None of the requested reference counts have been 1589 granted to the caller; the call is a no-op. 1590 E_UNEXPECTED An unspecified error occurred. It is unknown whether any or 1591 all of the requested reference counts have been granted. 1592 CO_E_OBJNOTREG Object is not registered. 1594 A useful optimization is for a caller to RemAddRef more than needed. 1596 When a process receives an out marshaled interface, it receives one 1597 reference 1598 count. If the process wishes to pass that interface as an out parameter, it 1599 must get another reference to pass along. Instead, the process (or 1600 middleman) 1601 should get a large number of references. Then if the interface is passed out 1602 multiple times, no new remote calls are needed to gain additional 1603 references. 1605 A marshaler may optionally specify more than one reference in the STDOBJREF 1606 when marshaling an interface. This allows the middle man case to pre-fill 1607 its 1608 cache of references without making an extra RemAddRef call. The number of 1609 references passed is always specified in the STDOBJREF field. 1611 If cPrivateRefs is not zero for all IPIDs, the call to RemAddRef must be 1612 made 1613 securely. DCOM on the server remembers the name of the client and the 1614 authentication and authorization service used to make to RemAddRef call. 1616 4.3.1 REMINTERFACEREF 1617 Member Type Semantic 1619 ipid IPID ipid to AddRef/Release. 1620 cPublicRefs unsigned long Number of public references granted. 1621 cPrivateRefs unsigned long Number of private references granted. Private 1622 references belong only to this client and can 1624 Brown/Kindel page 1625 33 1627 Internet Draft January, 1628 1998 1630 not be passed to other clients when marshaling 1631 the proxy. If a client has only private 1632 references and wishes to pass the proxy to 1633 some 1634 other client, it must first obtain some public 1635 references via IRemUnknown::RemAddRef and then 1636 pass one or more of those references in the 1637 STDOBJREF cPublicRefs field of the marshaled 1638 interface. 1640 4.4 IRemUnknown::RemRelease 1642 Release ownership of one or more reference counts on one or more IPIDs 1643 managed by the corresponding OXID. 1645 If cPrivateRefs is not zero for all IPIDs, the call to RemRelease must be 1646 made securely. For each IPID, DCOM maintains a table of reference counts 1647 indexed by the client identity (name, authn svc, authz svc). All public 1648 references are stored in one entry. Any call to RemRelease can release 1649 public references. Private references can only be released by the client 1650 that added them. 1652 Argument Type Semantic 1654 cRefs unsigned short The size of the rgRefs array. 1655 rgRefs REMINTERFACEREF[] An array of REMINTERFACEREFs, cRefs large. 1656 Each 1657 IPID indicates an interface managed by this 1658 OXID on whom more reference counts are being 1659 returned. The corresponding reference count, 1660 which may not be zero (and thus is one or 1661 more), indicates the number of reference 1662 counts 1663 returned on that IPID. 1665 Return Value Meaning 1667 S_OK Success. An attempt was made to release each of the requested 1668 interface references. 1669 E_INVALIDARG One or more of the IPIDs indicated were not in fact managed by 1670 this OXID, or one or more of the requested reference counts was 1671 zero. None of the offered reference counts have been accepted 1672 by 1673 the server; the call is a no-op. 1674 E_UNEXPECTED An unspecified error occurred. It is unknown whether any or all 1675 of the offered reference counts have been accepted. 1677 Brown/Kindel page 1678 34 1680 Internet Draft January, 1681 1998 1683 5. The OXID Resolver 1685 Each machine that supports the COM network protocol supports a one- per- 1686 machine service known as the machine's `OXID Resolver.' Communication with 1687 an 1688 OXID Resolver is via a DCE RPC, not an ORPC. 1690 The OXID Resolver performs several services: 1692 @ It caches and returns to clients when asked the string bindings necessary 1693 to connect to OXIDs of exported objects for which this machine is either 1694 itself a client or is the server. Note that it typically returns only to 1695 client processes on the same machine as itself, the OXIDs for which it is 1696 a 1697 client. 1699 @ It receives pings from remote client machines to keep its own objects 1700 alive. 1702 @ May do lazy protocol registration in the servers which it scopes. 1704 These services are carried out through an RPC interface (not a COM 1705 interface) 1706 known as IOXIDResolver. An OXID Resolver may be asked for the information 1707 required to connect to one of two different kinds of OXIDs, either the OXIDs 1708 associated with its own objects, or the OXIDs associated with objects for 1709 which it is itself a client The second case occurs when two or more client 1710 processes on the same machine ask their local OXID Resolver to resolve a 1711 given OXID. The client OXID Resolver in this case can cache the OXID 1712 information an return it to local clients without having to contact the 1713 server�s OXID Resolver again. 1715 5.1 OXID Resolver Ports/Endpoints 1717 The OXID Resolver resides at different endpoints (ports) depending on the 1718 transport being used. The OXID Resolver optimally resides at the same 1719 endpoints as the DCE RPC Endpoint Mapper (EPM). To accommodate systems where 1720 DCOM will coexist with existing DCE RPC installations (i.e., where an EPM 1721 and 1722 presumably a complete DCE RPC runtime already exists), the DCOM 1723 implementation on that system will register its interfaces with the DCE EPM 1724 and all DCOM implementations must be able to fall back if they make DCOM- 1725 specific calls on the DCE EPM endpoint which fail. 1727 Protocol String Description Endpoint 1728 Name(s) 1730 ncadg_ip_udp, ip CL over UDP/IP 135 1731 ncacn_ip_tcp CO over TCP/IP 135 1732 ncadg_ipx CL over IPX TBD 1734 Brown/Kindel page 1735 35 1737 Internet Draft January, 1738 1998 1740 ncacn_spx CO over SPX TBD 1741 ncacn_nb_nb CO over NetBIOS over NetBEUI TBD 1742 ncacn_nb_ipx CO over IPX TBD 1743 ncacn_http CO over HTTP 593 1745 5.2 The IOXIDResolver Interface 1747 IOXIDResolver (in earlier DCOM documentation this interface was named 1748 IObjectExporter) is defined as follows: 1750 [ 1751 uuid(99fcfec4-5260-101b-bbcb-00aa0021347a), 1752 pointer_default(unique) 1753 ] 1754 interface IOXIDResolver 1755 { 1756 // Method to get the protocol sequences, string bindings 1757 // and machine id for an object server given its OXID. 1758 [idempotent] error_status_t ResolveOxid 1759 ( 1760 [in] handle_t hRpc, 1761 [in] OXID *pOxid, 1762 [in] unsigned short cRequestedProtseqs, 1763 [in, ref, size_is(cRequestedProtseqs)] 1764 unsigned short arRequestedProtseqs[], 1765 [out, ref] DUALSTRINGARRAY **ppdsaOxidBindings, 1766 [out, ref] IPID *pipidRemUnknown, 1767 [out, ref] DWORD *pAuthnHint 1768 ); 1770 // Simple ping is used to ping a Set. Client machines use this 1771 // to inform the object exporter that it is still using the 1772 // members of the set. 1773 // Returns S_TRUE if the SetId is known by the object exporter, 1774 // S_FALSE if not. 1775 [idempotent] error_status_t SimplePing 1776 ( 1777 [in] handle_t hRpc, 1778 [in] SETID *pSetId // Must not be zero 1779 ); 1781 // Complex ping is used to create sets of OIDs to ping. The 1783 Brown/Kindel page 1784 36 1786 Internet Draft January, 1787 1998 1789 // whole set can subsequently be pinged using SimplePing, 1790 // thus reducing network traffic. 1791 [idempotent] error_status_t ComplexPing 1792 ( 1793 [in] handle_t hRpc, 1794 [in, out] SETID *pSetId, // In of 0 on first 1795 // call for new set. 1796 [in] unsigned short SequenceNum, 1797 [in] unsigned short cAddToSet, 1798 [in] unsigned short cDelFromSet, 1799 [in, unique, size_is(cAddToSet)] OID AddToSet[], 1800 // add these OIDs to the set 1801 [in, unique, size_is(cDelFromSet)] OID DelFromSet[], 1802 // remove these OIDs from the set 1803 [out] unsigned short *pPingBackoffFactor 1804 // 2^factor = multipler 1805 ); 1807 // In some cases the client maybe unsure that a particular 1808 // binding will reach the server. (For example, when the oxid 1809 // bindings have more then one TCP/IP binding) This call 1810 // can be used to validate the binding 1811 // from the client. 1812 [idempotent] error_status_t ServerAlive 1813 ( 1814 [in] handle_t hRpc 1815 ); 1817 // Method to get the protocol sequences, string bindings, RemoteUnknown 1818 IPID 1819 // and COM version for an object server given its OXID. Supported by 1820 DCOM 1821 // version 5.2 and above. 1823 [idempotent] error_status_t ResolveOxid2 1824 ( 1825 [in] handle_t hRpc, 1826 [in] OXID *pOxid, 1827 [in] unsigned short cRequestedProtseqs, 1828 [in, ref, size_is(cRequestedProtseqs)] 1829 unsigned short arRequestedProtseqs[], 1830 [out, ref] DUALSTRINGARRAY **ppdsaOxidBindings, 1831 [out, ref] IPID *pipidRemUnknown, 1833 Brown/Kindel page 1834 37 1836 Internet Draft January, 1837 1998 1839 [out, ref] DWORD *pAuthnHint, 1840 [out, ref] COMVERSION *pComVersion 1841 ); 1842 } 1844 5.2.1 IOXIDResolver::ResolveOxid and IOXIDResolver::ResolveOxid2 1846 Return the string bindings necessary to connect to a given OXID object. 1848 On entry, arRequestedProtseqs contains the protocol sequences the client is 1849 willing to use to reach the server. These should be in decreasing order of 1850 protocol preference, with no duplicates permitted. Local protocols (such as 1851 "ncalrpc") are not permitted. 1853 On exit, psaOxidBindings contains the string bindings that may be used to 1854 connect to the indicated OXID; if no such protocol bindings exist which 1855 match 1856 the requested protocol sequences, NULL may be returned. The returned string 1857 bindings are in decreasing order of preference of the server, with duplicate 1858 string bindings permitted (and not necessarily of the same preferential 1859 priority), though of course duplicates are of no utility. Local protocol 1860 sequences may not be present; however, protocol sequences that were not in 1861 the set of protocol sequences requested by the client may be. The string 1862 bindings returned need not contain endpoints; the endpoint mapper will be 1863 used as usual to obtain these dynamically. 1865 Version 5.2 of the DCOM wire protocol introduces a new method called 1866 ResolveOXID2 which allows a client to determine the version of a server�s 1867 COM 1868 implementation when it asks for OXID resolution. All clients must attempt to 1869 call this method to make sure that the major version of the server is one 1870 which they are capable of supporting. Clients who call this method and get 1871 an 1872 RPC_S_PROCNUM_OUT_OF_RANGE error can assume that the server supports version 1873 5.1 of the DCOM wire protocol. If the method call does succeed, the client 1874 should compare pComVersion->MajorVersion with the major version(s) that the 1875 client supports. If the client does not explicitly support the major version 1876 returned by the server, it should disconnect. 1878 The major version combined with the lower of the client�s and server�s minor 1879 versions should be inserted into the ORPCTHIS structure when issuing an ORPC 1880 to the server. 1882 Please see the IDL section above for notes on the differences between the 1883 minor versions of the DCOM wire protocol. 1885 Brown/Kindel page 1886 38 1888 Internet Draft January, 1889 1998 1891 Argument Type Description 1893 hRpc handle_t An RPC binding handle used to make the 1894 request. 1895 pOxid OXID* The OXID for whom string bindings are 1896 requested. 1897 cRequestedProtseqs unsigned The number of protocol sequences 1898 short requested. 1899 arRequestedProtseqs unsigned arRequestedProtseqs must be initialized 1900 short[] with all the protocol id's the client 1901 is 1902 willing to use to reach the server. It 1903 cannot contain local protocol 1904 sequences. 1905 The object exporter must take care of 1906 local lookups privately. The protocol 1907 sequences are in order of preference or 1908 random order. No duplicates are 1909 allowed. 1910 See the Lazy Protocol Registration 1911 section for more details. 1912 psaOxidBindings STRINGARRAY** The string bindings supported by this 1913 OXID, in preferential order. Note that 1914 these are Unicode strings. 1915 pipidRemUnknown IPID* The IPID to the IRemUnknown interface 1916 the 1917 OXID object for this OXID. 1918 pdwAuthnHint unsigned A value taken from the RPC_C_AUTHN 1919 long* constants. A hint to the caller as to 1920 the 1921 minimum authentication level which the 1922 server will accept. 1923 pComVersion COMVERSION* [ResolveOxid2 Only] A structure 1924 containing the major and minor version 1925 of 1926 the COM implementation on the server. 1928 Return Value Meaning 1930 S_OK Success. The requested information was returned. 1931 RPC_S_PROCNUM_OUT_OF_RANGE The procedure number is out of range (i.e. the 1932 function is not implemented). 1933 RPC_E_INVALID_OXID This OXID is unknown to this OXID Resolver, and 1934 thus no information was returned. 1935 E_UNEXPECTED An unspecified error occurred. Some of the 1936 requested information may not be returned. 1938 Brown/Kindel page 1939 39 1941 Internet Draft January, 1942 1998 1944 Object references are transient things. They are not meant to be stored in 1945 files or otherwise kept persistently. 1947 Conversely, since object references are aged, it is the responsibility of 1948 each client to unmarshal them and begin pinging them in a timely fashion. 1950 The basic use of the ResolveOxid method is to translate an OXID to string 1951 bindings. Put another way, this method translates an opaque process and 1952 machine identifier to the information needed to reach that machine and 1953 process. There are four interesting cases: 1955 1. Looking up an OXID the first time an interface is unmarshaled on a 1956 machine, 1958 2. Looking up an OXID between a pair of machines that already have 1959 connections, 1961 3. Looking up an OXID from a middleman, and 1963 4. Looking up string bindings with unresolved endpoints (lazy use protseq). 1965 Another interesting topic is garbage collection of stored string binding 1966 vectors. 1968 5.2.1.2 Lookup Between Friends 1970 Consider the case with two machines A and B. Machine A has a client process 1971 C 1972 and and OXID Resolver process D. Machine B has OXID Resolver process E and 1973 server process F. 1975 Server process F, when it starts up, registers it�s RPC string bindings with 1976 its local OXID Resolver process E, and creates an OBJREF to some object 1977 inside process F. At some future time client process C receives that OBJREF 1978 (Note: the mechanism used to acquire this OBJREF is not relevant to this 1979 discussion, it may have come through the object activation protocol (beyond 1980 the scope of this document) or as an [out] interface parameter in some other 1981 ORPC call, or through some other mechanism). The OBJREF contains the OXID 1982 for 1983 process F, and the string bindings for the Resolver process E on the server 1984 machine. 1986 Client Process C asks its local OXID Resolver to resolve the OXID for F. It 1987 passes it the OXID and the string bindings for OXID Resolver E. If Resolver 1988 D 1989 has never seen the OXID before, it calls the OXID Resolver E to ask it to 1990 resolve the OXID. Resolver E looks up the OXID and returns the string 1991 bindings for server process F. Resolver D then caches this information for 1992 future use, and returns the string bindings to client process C. Client 1993 process C then binds to the string bindings and is now able to make ORPC 1994 calls directly to the server process F. 1996 Brown/Kindel page 1997 40 1999 Internet Draft January, 2000 1998 2002 If other client processes on machine A receive an OBJREF for process F, the 2003 OXID resolve can be handled completely by the Resolver process D on machine 2004 A. There is no need to contact Resolver process E on the server again. 2006 If machine A gives an OBJREF for F to a client process on another machine G, 2007 then the Resolver process on G will repeat the same steps as Resolver 2008 process 2009 D did to resolve the OXID. 2011 +============+============+ +===========+===========+ 2012 | Machine A | | Machine B | 2013 +============+============+ +===========+===========+ 2014 +============+============+ +===========+===========+ 2015 | Process C | Resolver D | | Resolver E| Process F | 2016 +============+============+ +===========+===========+ 2017 | | | | | register | 2018 | | | | | endpoints | 2019 | | | | | with local| 2020 | | | | | Resolver E| 2021 +------------+------------+ +-----------+-----------+ 2022 | | | | cache F | | 2023 | | | | and it�s | | 2024 | | | | endpoints | | 2025 | | | | | | 2026 +------------+------------+ +-----------+-----------+ 2027 | receive | | | | | 2028 | OBJREF | | | | | 2029 | to F | | | | | 2030 | | | | | | 2031 +------------+------------+ +-----------+-----------+ 2032 | ask local | | | | | 2033 | Resolver D | | | | | 2034 | to resolve | | | | | 2035 | F | | | | | 2036 +------------+------------+ +-----------+-----------+ 2037 | | ask remote | | | | 2038 | | Resolver | | | | 2039 | | E to | | | | 2040 | | resolve F | | | | 2041 +------------+------------+ +-----------+-----------+ 2042 | | | | lookup F | | 2043 | | | | and | | 2044 | | | | return | | 2046 Brown/Kindel page 2047 41 2049 Internet Draft January, 2050 1998 2052 | | | | endpoints | | 2053 +------------+------------+ +-----------+-----------+ 2054 | | cache | | | | 2055 | | endpoints | | | | 2056 | | to F and | | | | 2057 | | return to C| | | | 2058 +------------+------------+ +-----------+-----------+ 2059 | bind to | | | | | 2060 | endpoint | | | | | 2061 | for F | | | | | 2062 | | | | | | 2063 +------------+------------+ +-----------+-----------+ 2064 | invoke | | | | | 2065 | method on | | | | | 2066 | F | | | | | 2067 | | | | | | 2068 +------------+------------+ +-----------+-----------+ 2070 5.2.1.4 Lazy Protocol Registration 2072 In a homogeneous network, all machines communicate via the same protocol 2073 sequence. In a heterogeneous network, machines may support multiple protocol 2074 sequences. Since it is often expensive in resources to allocate endpoints 2075 (RpcServerUseProtseq) for all available protocol sequences, ORPC provides a 2076 mechanism where they may be allocated on demand. To implement this extension 2077 fully, there are some changes in the server. However, changes are optional. 2078 If not implemented, ORPC will still work correctly if less optimally in 2079 heterogeneous networks. 2081 There are two cases: the server implements lazy protocol registration or it 2082 does not. 2084 If the server is using lazy protocol registration, the implementation of 2085 ResolveOxid is modified slightly. When the client OXID Resolver calls the 2086 server OXID Resolver, it passes the requested protocol sequence vector. If 2087 none of the requested protocol sequences have endpoints allocated in the 2088 server, the server OXID Resolver allocates them according to its own 2089 endpoint 2090 allocation mechanisms. 2092 If the server does not implement the lazy protocol registration, then all 2093 protocol sequences are registered by the server at server initialization 2094 time. 2096 Brown/Kindel page 2097 42 2099 Internet Draft January, 2100 1998 2102 When registering protocol sequences, the server may register endpoints and 2103 the server�s string bindings will contain the complete endpoints. However, 2104 if the server chooses not register endpoints when it registers protocol 2105 sequences the endpoint mapper process can be used to forward calls to the 2106 server. Using the endpoint mapper requires that all server IIDs be 2107 registered 2108 in the endpoint mapper. It also allows a different lazy protocol 2109 registration 2110 mechanism. The endpoint mapper can perform some local magic to force the 2111 server to register the protocol sequences. 2113 The client will always pass in a vector of requested protocol sequences 2114 which 2115 the server can ignore if it does not implement lazy protocol registration. 2117 5.2.2 IOXIDResolver::SimplePing 2119 Pings provide a mechanism to garbage collect interfaces. If an interface has 2120 references but is not being pinged, it may be released. Conversely, if an 2121 interface has no references, it may be released even though it has recently 2122 been pinged. SimplePing just pings the contents of a set. The set must be 2123 created with ComplexPing (section 5.2.3). 2125 Ping a set, previously created with IOXIDResolver::ComplexPing, of OIDs 2126 owned 2127 by this OXID Resolver. Note that neither IPIDs nor OIDs may be pinged, only 2128 explicitly created SETIDs. 2130 Argument Type Description 2132 hRpc handle_t An RPC binding handle used to make the request. 2133 PSetId SETID* A SETID previously created with 2134 IOXIDResolver::ComplexPing on this same OXID Resolver. 2136 Return Value Meaning 2138 S_OK Success. The set was pinged. 2139 RPC_E_INVALID_SET This SETID is unknown to this OXID Resolver, and thus the 2140 ping did not occur. 2141 E_UNEXPECTED An unspecified error occurred. It is not known whether 2142 the 2143 ping was done or not. 2145 5.2.3 IOXIDResolver::ComplexPing 2147 Ping a ping set. Optionally, add and/or remove some OIDs from the set. 2148 Optionally, adjust some ping timing parameters associated with the set. 2149 After 2150 a set is defined, a SimplePing will mark the entire contents of the set as 2152 Brown/Kindel page 2153 43 2155 Internet Draft January, 2156 1998 2158 active. After a set is defined, SimplePing should be used to ping the set. 2159 ComplexPing need only be used to adjust the contents of the set (or to 2160 adjust 2161 the time-out). 2163 Ping set ids (SETIDs) are allocated unilaterally by the server OXID 2164 Resolver. The client OXID Resolver then communicates with the server OXID 2165 Resolver to add (and later remove) OIDs from the ping set.. 2167 Each OID owned by a server OXID Resolver may be placed in zero or more ping 2168 sets by the various clients of the OID. The client owner of each such set 2169 will set a ping period and a ping time-out count for the set, thus 2170 determining an overall time-out period for the set as the product of these 2171 two values. The time-out period is implicitly applied to each OID contained 2172 in the set and to future OIDs that might add be added to it. The server OXID 2173 Resolver is responsible for ensuring that an OID that it owns does not 2174 expire 2175 until at least a period of time t has elapsed without that OID being pinged, 2176 where t is the maximum time-out period over all the sets which presently 2177 contain the given OID, or, if OID is not presently in any such sets but was 2178 previously, t is the time-out period for the last set from which OID was 2179 removed at the instant that that removal was done; otherwise, OID has never 2180 been in a set, and t is a default value (ping period equals 120 seconds, 2181 ping 2182 time-out count equals three (3), t equals 360 seconds, or six (6) minutes). 2184 Clients are responsible for pinging servers often enough to ensure that they 2185 do not expire given the possibility of network delays, lost packets, and so 2186 on. If a client only requires access to a given object for what it would 2187 consider less than a time-out period for the object (that is, it receives 2188 and 2189 release the object in that period of time), then unless it is certain it has 2190 not itself passed the object to another client, it must be sure to 2191 nevertheless ping the object (a ComplexPing that both adds and removes the 2192 OID will suffice). This ensures that an object will not expire as it is 2193 passed through a chain of calls from one client to another. 2195 An OID is said to be pinged when a set into which it was previously added 2196 and 2197 presently still resides is pinged with either a SimplePing or a ComplexPing, 2198 or when it is newly added to a set with ComplexPing. Note that these rules 2199 imply that a ComplexPing that removes an OID from a set still counts as a 2200 ping on that OID. In addition to pinging the set SETID, this call sets the 2201 time-out period of the set as the product of a newly-specified ping period 2202 and a newly-specified "ping count to expiration;" these values take effect 2203 immediately. Ping periods are specified in tenths of a second, yielding a 2204 maximum allowable ping period of about 1 hr 50 min. 2206 Adjustment of the time-out period of the set is considered to happen before 2207 the addition of any new OIDs to the set, which is in turn considered to 2208 happen before the removal of any OIDs from the set. Thus, an OID that is 2210 Brown/Kindel page 2211 44 2213 Internet Draft January, 2214 1998 2216 added and removed in a single call no longer resides in the set, but is 2217 considered to have been pinged, and will have as its time-out at least the 2218 time-out period specified in that ComplexPing call. 2220 On exit, the server may request that the client adjust the time-out period; 2221 that is, ask it to specify a different time-out period in subsequent calls 2222 to 2223 ComplexPing. This capability can be used to reduce traffic in busy servers 2224 or 2225 over slow links. The server indicates its desire through the values it 2226 returns through the variables pReqSetPingPeriod and 2227 pReqSetNumPingsToTimeOut. 2228 If the server seeks no change, it simply returns the corresponding values 2229 passed by the client; if it wishes a longer time-out period, it indicates 2230 larger values for one or both of these variables; if it wishes a smaller 2231 period, it indicates smaller values. When indicating a larger value, the 2232 server must start immediately acting on that larger value by adjusting the 2233 time-out period of the set. However, when indicating a smaller value, it 2234 must 2235 consider its request as purely advice to the client, and not take any 2236 action: 2237 if the client wishes to oblige, it will do so in a subsequent call to 2238 ComplexPing by specifying an appropriate time-out period. 2240 Argument Type Description 2242 hRpc handle_t An RPC binding handle used to make the 2243 request. 2244 pSetId SETID The SETID being manipulated. SequenceNum 2245 unsigned short The sequence number allows 2246 the object exporter to detect duplicate 2247 packets. Since the call is idempotent, it 2248 is 2249 possible for duplicates to get executed and 2250 for calls to arrive out of order when one 2251 ping is delayed. 2252 cAddToSet unsigned The size of the array AddToSet. 2253 short 2254 cDelFromSet unsigned The size of the array DelFromSet. 2255 short 2256 AddToSet OID[] The list of OIDs which are to be added to 2257 this set. Adding an OID to a set in which 2258 it 2259 already exists is permitted; such an 2260 action, 2261 as would be expected, is considered to ping 2262 the OID. 2263 DelFromSet OID[] The list of OIDs which are to be removed 2264 from this set. Removal counts as a ping. An 2265 OID removed from a set will expire after 2266 the 2267 number of ping periods has expired without 2269 Brown/Kindel page 2270 45 2272 Internet Draft January, 2273 1998 2275 any pings (not the number of ping periods - 2276 1). If an id is added and removed from a 2277 set 2278 in the same ComplexPing, the id is 2279 considered to have been deleted. 2280 pPingBackoffFactor unsigned Acts as a hint (only) from the server to 2281 the 2282 short* client in order to reduce ping traffic. 2283 Clients are requested to not ping more 2284 often 2285 than (1<<*pPingBackoffFactor)* 2286 (BasePingInterval=120) seconds, and the 2287 number of pings until timeout remains 2288 unchanged at the default of 3. Clients may 2289 choose to assume that this parameter is 2290 always zero. 2292 Return Value Meaning 2294 S_OK Success. The set was pinged, etc. 2295 RPC_E_INVALID_OID Indicates that some OID was not recognized. There is no 2296 recovery action for this error, it is informational only. 2297 E_ACCESSDENIED Access is denied. 2298 E_OUTOFMEMORY There was not enough memory to service the call. The 2299 caller may retry adding OIDs to the set on the next ping. 2300 E_UNEXPECTED An unspecified error occurred. It is not known whether 2301 the 2302 ping or any of the other actions were done or not. 2304 6. Object Activation 2306 Each machine that supports the COM network protocol also supports a one-per- 2307 machine interface called IRemoteActivation (which supersedes ISCMtoSCM in 2308 previous drafts of this document). This interface contains one method �- 2309 RemoteActivation �- used to activate a class object associated with a 2310 caller- 2311 supplied CLSID, file moniker, or IStorage pointer. 2313 6.1 IRemoteActivation Ports/Endpoints 2315 IRemoteActivation resides at the same endpoints as the IOXIDResolver 2316 interface. Please see section 5.1 for more information. 2318 Brown/Kindel page 2319 46 2321 Internet Draft January, 2322 1998 2324 6.2 The IRemoteActivation Interface 2326 IRemoteActivation is defined as follows: 2328 [ 2329 uuid(4d9f4ab8-7d1c-11cf-861e-0020af6e7c57), 2330 pointer_default(unique) 2331 ] 2333 interface IRemoteActivation 2334 { 2335 import "obase.idl"; 2337 const unsigned long MODE_GET_CLASS_OBJECT = 0xffffffff; 2339 HRESULT RemoteActivation( 2340 [in] handle_t hRpc, 2341 [in] ORPCTHIS *ORPCthis, 2342 [out] ORPCTHAT *ORPCthat, 2343 [in] GUID *Clsid, 2344 [in, string, unique] WCHAR *pwszObjectName, 2345 [in, unique] MInterfacePointer *pObjectStorage, 2346 [in] DWORD ClientImpLevel, 2347 [in] DWORD Mode, 2348 [in] DWORD Interfaces, 2349 [in,unique,size_is(Interfaces)] IID *pIIDs, 2350 [in] unsigned short cRequestedProtseqs, 2351 [in, size_is(cRequestedProtseqs)] 2352 unsigned short RequestedProtseqs[], 2353 [out] OXID *pOxid, 2354 [out] DUALSTRINGARRAY **ppdsaOxidBindings, 2355 [out] IPID *pipidRemUnknown, 2356 [out] DWORD *pAuthnHint, 2357 [out] COMVERSION *pServerVersion, 2358 [out] HRESULT *phr, 2359 [out,size_is(Interfaces)] MInterfacePointer **ppInterfaceData, 2360 [out,size_is(Interfaces)] HRESULT *pResults 2361 ); 2362 } 2364 6.2.1 IRemoteActivation::RemoteActivation 2366 Brown/Kindel page 2367 47 2369 Internet Draft January, 2370 1998 2372 Activates the class object specified by Clsid, associated with the 2373 pwszObjectName file moniker, or associated with pObjectStorage -- a client- 2374 provided IStorage object --, and gives the client the OXID and IPID(s) of 2375 any 2376 interfaces it requested on that object. Implementations are free to return a 2377 new instance of the requested class object every time this API is called or 2378 to return the same class object (i.e. the same OXID and IPIDs) every time. 2379 Implementations may choose to offer �launch� functionality by loading and 2380 initializing the executable code which implements the requested class object 2381 if it is not already running, or if the programmer wishes to have objects 2382 segregated into different processes because of security or robustness 2383 considerations. 2385 This function incorporates the functionality of both the IRemUnknown and 2386 IOXIDResolver interfaces so that only one network roundtrip is necessary for 2387 object activation. 2389 Argument Type Description 2391 hRpc handle_t An RPC binding handle used to make 2392 the request. 2393 ORPCthis ORPCTHIS* Client-provided ORPCTHIS 2394 ORPCthat ORPCTHAT* Server-provided ORPCTHAT 2395 Clsid const GUID* The CLSID of the class object the 2396 caller wishes to activate. 2397 pwszObjectName WCHAR* Path to a file name which when 2398 activated by the server�s moniker 2399 facility, will return the object 2400 that the client is interested in. 2401 pObjectStorage MInterfacePointer* Interface pointer to an object on 2402 the client which supports 2403 IStorage. 2404 The server on the remote will use 2405 the IStorage�s CLSID to determine 2406 which object to instantiate on the 2407 server. 2408 ClientImpLevel DWORD A value taken from the RPC_C_IMP 2409 constants. Used to inform the 2410 server of the client�s default 2411 impersonation level. 2412 Mode DWORD Set to MODE_GET_CLASS_OBJECT for 2413 regular object activations. If 2414 pwszObjectName or pObjectStorage 2415 are not NULL, this mode is passed 2417 Brown/Kindel page 2418 48 2420 Internet Draft January, 2421 1998 2423 to IPersistFile::Load when 2424 activating the object on the 2425 server. 2426 Interfaces DWORD The number of interfaces being 2427 requested. 2428 pIIDs IID* The list of IIDs that name the 2429 interfaces sought on this object. 2430 cRequestedProtseqs Unsigned short The number of protocol sequences 2431 specified in the RequestedProtseqs 2432 parameter. 2433 RequestedProtseqs Unsigned short[] The list of protocol sequences 2434 that 2435 the client wants OXID binding 2436 handles for. 2437 pOxid OXID* The OXID for the object created. 2438 ppdsaOxidBindings DUALSTRINGARRAY** Endpoint and security binding 2439 strings to reach the OXID 2440 pipidRemUnknown IPID* The IPID of the OXID�s IRemUnknown 2441 interface 2442 pAuthnHint DWORD* A value taken from the RPC_C_AUTHN 2443 constants. A hint to the caller as 2444 to the minimum authentication 2445 level 2446 which the server will accept. 2447 pServerVersion COMVERSION* The version of the COM 2448 implementation on the server. 2449 phr HRESULT* The HRESULT for the activation 2450 operation 2451 ppInterfaceData MInterfacePointer** The set of interface pointers 2452 requested. Returned in the order 2453 they were requested in pIIDs. 2454 pResults HRESULT* The HRESULTs for the individual 2455 QueryInterface() operations 2456 performed on the interfaces 2457 specified in Interfaces. 2459 Return Value Meaning 2461 RPC_S_OK This method always returns RPC_S_OK. Check phr for the 2462 status of this function. 2464 Value of phr Meaning 2466 E_UNEXPECTED An unspecified error occurred. 2467 E_ACCESSDENIED Client attempted to activate but did not have the 2468 required permission or the server does not permit 2470 Brown/Kindel page 2471 49 2473 Internet Draft January, 2474 1998 2476 remote activations. 2477 E_INVALIDARG One or more arguments are invalid. 2478 E_OUTOFMEMORY Insufficient memory to complete the operation. 2480 7. Security Considerations 2482 In general, like any generic data transfer protocol, DCOM cannot regulate 2483 the 2484 content of the data that is transferred, nor is there any a priori method of 2485 determining the sensitivity of any particular piece of information within 2486 the 2487 context of any given ORPC. 2489 Specifically, however, DCOM entirely leverages the security infrastructure 2490 defined by DCE RPC, which allows for various forms of authentication, 2491 authorization, and message integrity. 2493 Further details TBS. 2495 8. Acknowledgements 2497 As previously noted, the DCOM protocol highly leverages the DCE RPC 2498 Specification [CAE RPC], and we again acknowledge its usefulness to this 2499 specification. 2501 The DCOM protocol itself is the combined effort of a large number of people. 2502 The following individuals in particular were critical to the definitions 2503 which appear in this specification. 2505 Bob Atkinson Alex Armanasu (Mitchell) 2506 Deborah Black Vibhas Chandorkar 2507 Richard Draves Mario Goertzel 2508 Rick Hill Gregory Jensenworth 2509 David Kays Paul Leach 2510 Michael Nelson Kevin Ross 2511 Mark Ryland Bharat Shah 2512 Tony Williams 2514 9. References 2516 [CAE RPC] CAE Specification, X/Open DCE: Remote Procedure Call, X/Open 2517 Company Limited, Reading, Berkshire, UK (xopen.co.uk), 1994. X/Open 2518 Document Number C309. ISBN 1-85912-041-5. (also available online 2519 through 2520 from the OSF at ) 2522 Brown/Kindel page 2523 50 2525 Internet Draft January, 2526 1998 2528 [COM] The Component Object Model Specification, Version 0.99, November, 2529 1996, 2530 Microsoft Corporation. (also available online from Microsoft at 2531 . Note that this 2532 reference is circular because this document (the DCOM wire protocol 2533 specification) is the same chapter 15 of the COM Specification. 2535 10. Author's Addresses 2537 Nat Brown, One Microsoft Way Redmond, WA 98052-6399, U.S.A. Fax: +1 (206) 2538 936 2539 7329 Email: 2541 Charlie Kindel, One Microsoft Way Redmond, WA 98052-6399, U.S.A. Fax: +1 2542 (206) 936 7329 Email: 2544 Brown/Kindel page 2545 51