CH15 Network Protocol

The COM Specification
Chapter 15. COM Network Protocol
0Part V: The COM Library

It should be clear by this time that COM itself involves some systems-level code, that is, some implementation of its own. However, at the core the Component Object Model by itself is a specification (hence Model!" for how objects and their clients interact throu#h the binary standard of interfaces. $s a specification it defines a number of other standards for interoperability% &he fundamental process of interface ne#otiation throu#h
QueryInterface.
$ reference counting mechanism throu#h objects (and their resources" are mana#ed even when connected to multiple clients. 'ules for memory allocation and responsibility for those allocations when e(chan#ed between independently developed components.
Consistent and rich error reportin# facilities. In addition to bein# a specification, COM is also an implementation contained what is called the COM )ibrary.! &he implementation is provided throu#h a library (such as a *)) on Microsoft +indows" that includes% $ small number of fundamental $,I functions that facilitate the creation of COM applications, both clients and servers. -or clients, COM supplies basic object creation functions. for servers the facilities to e(pose their objects. Implementation locator services throu#h which COM determines from a class identifier which server implements that class and where that server is located. &his includes support for a level of indirection, usually a system re#istry, between the identity of an object class and the pac/a#in# of the implementation such that clients are independent of the pac/a#in# which can chan#e in the future. &ransparent remote procedure calls when an object is runnin# in a local or remote server. &his includes the implementation of a standard networ/ wire-protocol.
$ standard mechanism to allow an application to control how memory is allocated within its process. In #eneral, only one vendor needs to, or should, implement a COM )ibrary for any particular operatin# system. -or e(ample, Microsoft has implemented COM on Microsoft +indows 0.1, Microsoft +indows 23, Microsoft +indows 4&, and the $pple Macintosh. &he followin# chapter describes elements of the COM )ibrary that a vendor implementin# COM on a previously unsupported platform would re5uire.
DRAFT
Page 1
Cop!right " 1##5 Micro$oft Corporation All Right$ Re$er%e&
Component Object Model Network Protocol

&he COM networ/ protocol is a protocol for object-oriented remote procedure calls and is thus also called Object ',C or O',C. &he Object ',C protocol consists of a set of e(tensions, layered on the distributed computin# environment (*C6" ',C specification. &he Object ',C protocol specifies% How calls are made on an object How object references are represented, communicated, and maintained
Overview
&he Object ',C protocol hi#hly levera#es the O7- *C6 ',C networ/ protocol (see the reference 8C$6 ',C9". &his levera#e occurs at both the specification level and the implementation level% the bul/ of the implementation effort involved in implementin# the COM networ/ protocol is in fact that of implementin# the *C6 ',C networ/ protocol on which it is built.
Object Calls
$n actual COM networ/ remote procedure call (hereinafter referred to as an O',C!" is in fact a true *C6 remote procedure call (herein termed a *C6 ',C!", a 'e5uest ,*:! conformin# to the specification for such calls per 8C$6 ',C9. In an O',C, the object I* field of the invocation header as specified in 8C$6 ',C9 contains an IPID!. $n IPID is a 1;<-bit identifier /nown as an interface pointer i&entifier which represents a particular interface on a particular object in a particular server. $s it is passed in the object I* fields of a *C6 ',C, the static type of an IPID is in fact a UUID. However, IPIDs are scoped not #lobally but rather only relative to the machine on which the server is located (and which thus ori#inally allocated them". IPIDs do not necessarily use the standard UUID allocation al#orithm, but rather may use a machine-specific al#orithm Thi$ page intentionall! left (lank. which can assist with dispatchin#. 1 In an O',C, the interface I* field of the ',C header specifies the IID, and ar#uments are found in the body, as usual.; However, when viewed from the *C6 ',C perspective an additional first ar#ument is always present that is absent in the correspondin# COM interface specification. &his ar#ument is of type ORPCTHIS, which is described below. It is placed first in the body of the 'e5uest ,*:, before the actual ar#uments of the O',C. It is specifically le#al for an O',C to attempt a call a method number on a #iven interface which is beyond the number of methods believed by the server to be in that interface. 7uch calls should cause a fault. 7imilarly, in a reply to an O',C (a *C6 ',C 'esponse ,*:!", when viewed from the *C6 ',C perspective, an additional first return value is always present that is absent in the correspondin# COM interface specification. &his ar#ument is of type ORPCTHAT, which is also described below. It is placed first in the body of the 'esponse ,*:, before the actual return values of the O',C. $n ORPCTHAT may also be present in a -ault ,*:.! In the Connectionless (C)" -ault ,*:, 0 it is placed four bytes after the 0;-bit fault code which normally comprises the entire body of the ,*:, thus achievin# ei#ht byte ali#nment for the ORPCTHAT. the intervenin# paddin# bytes are presently reserved and must be =ero. &he ,*: body len#th > is of course set to encompass the entire body of the -ault ,*:, includin# the ORPCTHAT. In the Connection-oriented (CO" -ault ,*:, the ORPCTHAT is placed in the standard location
1 ;
0 >
$s in *C6 ',C object I*s are indeed only ever interpreted relative to a #iven machine, this rela(in# of the *C6 specification is not problematic. &he II* in the interface I* field is from a lo#ical perspective actually redundant because the I,I* uni5uely specifies an interface pointer (thou#h the II* is not recoverable from just the I,I*". However, an additional (optional" chec/ to verify that the caller and callee a#ree on the type of the interface pointer would ma/e the system more robust. $lso, the specification of the actual II* in 5uestion eases the inte#ration of the COM networ/ protocol with the *C6 ',C networ/ protocol. 4ote that it is not e(pensive for callers to provide the II* since the space for the II* is allocated in the *C6 ',C header, which is always transmitted anyway. -or the specification of the Connectionless -ault ,*:, see 8C$6 ',C9, pa#e 3;?. ,a#e 303 of the same wor/ describes the Connection-oriented -ault ,*:. Ibid, pa#e 31@. Page ' DRAFT
allocated for the stub data.! 3 In a -ault ,*: of either form that results from an O',C, if an not present then no other data may be substituted in its here-specified location in the ,*:.
ORPCTHAT is
OXIDs, Object Exporters, & Machines

$lthou#h an IPID from a lo#ical perspective semantically determines the server, object and interface to which a particular call should be directed, it does not by itself indicate the bindin# information necessary to actually carry out an invocation. &he protocol represents this how-to! communication information in a UUID called an object e(porter identifier, otherwise /nown as an OXID. Conceptually, an OXID can be thou#ht of as an implementation scope for an COM object, which may be a whole machine, a #iven process, a thread within that process, or other more esoteric implementation scope, but the e(act definition of such scopes has no bearin# on the COM networ/ protocol. $ #iven machine at any moment may support several OXIDs. however there is always a uni5ue O()ect *+porter $er%ice per machine which coordinates the mana#ement of all the OXIDs on the machine. *ata structures in each Object 6(porter /eep trac/ of the IPIDs e(ported and imported by that Object 6(porter. &he Object 6(porter resides at well-/nown endpoints (one per protocol, of course" on the machine. It supports a *C6 ',C interface /nown as IObjectExporter, which is described below. $n OXID is used to determine the ',C strin# bindin#s that allow calls to reach their tar#et IPID. Aefore ma/in# a call, the callin# process must translate an OXID into a set of bindin#s that the underlyin# ',C implementation understands. It accomplishes by maintainin# a cache of these mappin#s. +hen the destination application receives an object reference, it chec/s to see if it reco#ni=es the OXID. If it does not, then it as/s the source of the object reference (the server machine from which the object reference was ac5uired, which is not necessarily the home machine for the interface pointer" for the translation, and saves the resultin# set of strin# bindin#s in a local table that maps OXIDs to strin# bindin#s. $ssociated with each OXID (not each Object 6(porter" is COM object termed an OXID object.! OXID objects implement (at least" the IRe Un!no"n interface, throu#h which remote mana#ement of reference counts and re5uests for interfaces are returned. 6ach machine is represented by a #ID. #IDs are UUIDs and thus universally uni5ue. &he #ID for a machine may (should" chan#e when the machine reboots. However, when the #ID for a machine chan#es, all OBI*s, OIDs, and IPIDs on that machine become invalid. #IDs are an optimi=ation to simplify the tas/ of determinin# which OXIDs are e(ported and pin#ed by which object e(porters.
Marshaled Interface References

&he COM networ/ protocol e(tends the 4etwor/ *ata 'epresentation standard specified in 8C$6 ',C9 by definin# what can be thou#ht of as a new primitive data type that can be marshaled% that of an interface reference to a COM object.@ &his is the only e(tension to 4*' made by the COM networ/ protocol. $ marshaled interface references is described by a type /nown as an O$%RE&, which is described in detail below. $n O$%RE& in actuality has several variations% Null. Standard. A standard remote reference. Known as a STDO$%RE&. A STDO$%RE& contains: $n IPID, which uni5uely specifies the interface and object. $n object I* (OID", which uni5uely specifies the identity of the object on which the found. OIDs are UUIDs. they are universally uni5ue.
IPID
is
$n OXID, which identifies the scope where the implementation of the object is active, and can be used to reach the interface pointer. C
3 @ C
&hat is, in the Connection-oriented case, the ORPCTHAT also follows four bytes of paddin# after the fault code. however, the fault code in the Connection-oriented -ault ,*: is preceded other data not found in the Connectionless -ault ,*:. Consult 8C$6 ',C9 for further details. +hether one actually thin/s of this as a new primitive data type or new compositional operator over e(istin# data types depends on oneDs point of view. Aoth positions have some merit. 4ote that the object reference does not include the interface identifier (II*", althou#h you canDt do much with the object reference without /nowin# the II*. &he I,I* does uni5uely specify an II*. however, you canDt al#orithmically derive the II* from the I,I*. &his is not a problem because the II* does not have to be e(plicitly specified. it is either implicitly specified (by the type of the ar#ument in a MI*) declaration" or available e(plicitly as another ar#ument in the call that is carryin# the polymorphic object reference (for e(ample, I:n/nown%%EueryInterface". Page , Cop!right " 1##5 Micro$oft Corporation All Right$ Re$er%e&
DRAFT
$ reference count, indicatin# the number of references to this IPID that are conveyed by this marshalin#. &his count, thou#h typically a value of one, may in fact be =ero, one, or more (see the ne(t section". 7ome fla#s, e(plained later.
Long. A standard reference, along with a set of protocol sequences and network addresses that can be useful when marshaling a proxy to give to another machine (a.k.a. the middle-man case). Custom. Contains a class ID (CLSID) and class-specific information. The Custom format gives an object control over the representation of references to itself. For example, an immutable object might be passed by value, in which case the classspecific information would contain the objects immutable data. Handler. A sub-case of the custom reference in which the class-specific information is standardized. For example, an object wishes to be represented in client address spaces by a proxy object that caches state. In this case, the class-specific information is just a standard reference to an interface pointer that the handler (proxy object) will use to communicate with the original object.
Long Handler: Contains the same information as the handler case as well as the object resolver address. This form is needed for the same reason the long form is needed. Interface references are alwa!$ marshaled in little-endian byte order, irrespective of the byte order prevailin# in the remainder of the data bein# marshaled.
Reference Counting
In the COM networ/ protocol, remote reference countin# is conducted on per interface (per IPID", just as local reference countin# is carried out on a per interface basis. &he actual increment and decrement calls are carried out usin# (respectively" the Re A''Ref and Re Re(ease methods in a COM interface /nown as IRe Un!no"n found on an object associated with the each OXID, the IPID of which is returned from the function IObjectExporter))*etStr+n,$+n'+n,s (see below". In contrast to their analo#ues in IUn!no"n, Re A''Ref and Re Re(ease can in one call increment or decrement the reference count of many different IPIDs by an arbitrary amount. this allows for #reater networ/ efficiency. In the interests of performance, client COM implementations typically do not immediately translate each local A''Ref and Re(ease into a remote Re A''Ref and Re Re(ease. 'ather, the actual remote release of all interfaces on an object is typically deferred until all local references to all interfaces on that object have been released. -urther, one actual remote reference count may be used to service many local reference counts. that is, the client infrastructure may multiple( =ero or more local references to an interface into =ero or one remote references on the actual IPID.<
Pinging
&he above reference countin# scheme would be entirely ade5uate on its own if clients never crashed, but in fact they do, and the system needs to be robust in the face of clients crashin# when they hold remote references. In a *C6 ',C, one typically addresses this issue throu#h the use of conte(t handles . Conte(t handles are not used, however, by the COM networ/ protocol, for reasons of e(pense. &he basic underlyin# technolo#y used in virtually all protocols for detectin# remote crashes is that of periodic pin#s. 4aive use of ',C conte(t handles would result in per object per client process pin#s bein# sent to the server. &he COM networ/ protocol architects its pin#in# infrastructure to reduce networ/ traffic by relyin# on the client Object 6(porter implementation to do local mana#ement of client liveness detection, and havin# the actual pin#s be sent only on a machine to machine basis. ,in#in# is carried out on a per-object (per OID", not a per-interface (per IPID" basis. $rchitecturally, at its server machine, each e(ported object (each e(ported OID" has associated with it a p+n,Per+o' time value and a nu P+n,sToT+ eOut count which to#ether (throu#h their product" determine the overall amount of time /nown as the pin# period! that must elapse without receivin# a pin# on that OID or an invocation on one of its IPIDs before all the remote references to IPIDs associated with that OID can be considered to have
<
$ conse5uence of allowin# for this optimi=ations is that the reference count on each IPID as seen by the server may be in fact less than the total number of references on that interface as seen by all the e(tant clients of that interface. Page DRAFT
e(pired. Once e(piration has occurred, the interfaces behind the IPIDs can as would be e(pected be reclaimed solely on the basis local /nowled#e, thou#h the timeliness with which this is carried out, if at all, is an implementation specific. If the server COM infrastructure defers such #arba#e collection in this situation (perhaps because it has local references /eepin# the interface pointer alive" and it later hears a pin# or receives a remote call, then it /nows a networ/ partition healed. It can consider the e(tant remote references to be reactivated and can continue remote operations. +hen interface pointers are conveyed from one client to another, such as bein# passed as either -+n. or -out. parameters to a call, the interface pointer is marshaled in one client and unmarshaled in the other. In order to successfully unmarshal the interface, the destination client must obtain at least one reference count on the interface. &his is usually accomplished by passin# in the marshaled interface STDO$%RE& a cRefs of (at least" one. the destination client then ta/es ownership of that many (more" reference counts to the indicated IPID, and the source client then owns that many fewer reference counts on the IPID. It is le#al, however, for =ero reference counts to be passed in the STDO$%RE&. here, the destination client must (if it does not already have access to that IPID and thus have a non-=ero reference count for it" before it successfully unmarshals the interface reference (concretely, e.#., before CoUn ars/a(Interface returns" call to the objectDs e(porter usin# IRe Un!no"n))Re A''Ref to obtain a reference count for it. If the destination client is in fact the objectDs server, then special processin# is re5uired by the destination client. &he remote reference counts bein# passed to it should, in effect, be Fta/en out of circulation,F as what where heretofore remote references are bein# converted into local references. &hus, the reference counts present in the 7&*OAG'6- are in fact decremented from the remote reference count for the IPID in 5uestion. 7ome objects have a usa#e model such that they do not need to be pin#ed at all. such objects are indicated by the presence of a fla# in a STDO$%RE& to an interface on the object. Objects which are not pin#ed in fact need not be reference counted either, thou#h it is le#al (but pointless" for a client to reference count the IPIDs of such objects. -or all other objects, assumin# a non-=ero pin# period, it is the responsibility of the holder of an interface reference on some object to ensure that pin#s reach the server fre5uently enou#h to prevent e(piration of the object. &he fre5uency used by a client depends on the pin# period, the reliability of the channel between the client and the server, and the probability of failure (no pin#s #ettin# throu#h and possible premature #arba#e-collection" that the client is willin# to tolerate. &he pin# pac/et and H or its reply may both re5uest chan#es to the pin# period. &hrou#h this mechanism, networ/ traffic may be reduced in the face of slow lin/s busy servers. Delta Pin in +ithout any further refinements, pin# messa#es could be 5uite hefty. If machine $ held 1?;> remote objects (OIDs" on machine A, then it would send 1@I byte pin# messa#es. &his would be annoyin# if the set of remote objects was relatively stable and the pin# messa#es were the same from pin# to pin#. &he delta mechanism reduces the si=e of pin# messa#es. It uses a pin#-set interface that allows the pin#in# of a sin#le set to replace the pin#in# of multiple OIDs. Instead of pin#in# each OID, the client defines a set. 6ach pin# contains only the set id and the list of additions and subtractions to the set. Objects that come and #o within one pin# period are removed from the set without ever havin# been added. &he pin#in# protocol is carried out usin# two methods in the (*C6" interface IObjectExporter on the Object 6(porter% Co p(exP+n,, and S+ p(eP+n,. Co p(exP+n, is used to by clients to #roup the set of OIDs that they must pin# into UUID-ta##ed sets /nown to the server. &hese entire sets of OIDs can then be subse5uently pin#ed with a sin#le, short, call to S+ p(eP+n,.
uer!Interface
&he IRe Un!no"n interface on the object-e(porter specified object, in addition to servicin# reference countin# as described above also services QueryInterface calls for remote clients for IPIDs mana#ed by that e(porter. IRe Un!no"n))Re QueryInterface differs from IUn!no"n))QueryInterface in much the same way as Re 0 A''Ref and Re Re(ease differ from A''Ref and Re(ease1 in that it is optimi=ed for networ/ access by bein# able to retrieve many interfaces at once.
DRAFT
Page 5
Causalit! ID
6ach O',C carries with it a UUID /nown as the causality id that connects to#ether the chain of O',C calls that are causally related. If an out#oin# O',C is made while servicin# an incomin# O',C, the out#oin# call is to have the same causality id as the incomin# call. If an out#oin# O',C is made while not servicin# an incomin# O',C, then a new causality id is allocated for it. Causality ids may in theory be reused as soon as it is certain that no transitively outstandin# call is still in pro#ress which uses that call. In practice, however, in the face of transitive calls and the possibility of networ/ failures in the middle of such call chains, it is difficult to /now for certain when this occurs. &hus, pra#matically, causality ids are not reusable. &he causality id can be used by servers to understand when bloc/in# or deferrin# an incomin# call (supported in some COM server pro#rammin# models" is very hi#hly probable 2 to cause a deadloc/, and thus should be avoided. &he causality id for aybe, +'e potent, and broa'cast calls must be set to null. 1? If a server ma/es a O',C call while processin# such a call, a new causality id must be #enerated as if it were a top level call.
Data type! and !tr"ct"re!

&his followin# several sections present the technical details of the COM networ/ protocol. &he notation used herein is that of the Microsoft Interface *efinition )an#ua#e, version ; (MI*)". MI*) is a upwardly compatible e(tension to the *C6 I*) lan#ua#e specified in 8C$6 ',C9. *etails of the MI*) lan#ua#e specification are available from Microsoft Corporation.
DCE Pac"et #eaders

Object RPC sits entirely on top of DCE RPC. The following list describes the elements of ORPC that are specified above and beyond DCE RPC. The object id field of the header must contain the IPID. The interface id of the RPC header must contain the IID, even though it is not needed given the IPID. This allows ORPC to sit on top of DCE RPC. An unmodified DCE RPC implementation will correctly dispatch based on IID and IPID. An optimized RPC need only dispatch based on IPID. An IPID uniquely identifies a particular interface on a particular object on a machine. The converse is not true; a particular interface on a particular object may only be represented by multiple IPIDs. IPIDs are unique on their OXID. IPIDs may be reused, however reuse of IPIDs should be avoided.
Data,ra 1 aybe1 and +'e potent calls aybe or +'e potent calls.
are all allowed in ORPC. Interface pointers may not be passed on
Datagram broadcasts are not allowed in ORPC. Remote COM input synchronous calls are not allowed in ORPC. COM asynchronous calls are synchronous RPC calls. COM faults are returned in the stub fault field of the DCE RPC fault packet. Any 32 bit value may be returned. Only the following value is pre-specified:
RPC2E23ERSIO42#IS#ATCH
COM will allow DCE cancel. $ll interface version numbers must be 5.5.
Object RPC $ase Definitions

&here are several fundamental data types and structures on which the COM networ/ protocol is built. &hese are defined in the MI*) file O$ASE.ID6, which is included below%
[
2
1?
&his has hi#h probability and not certainty due to some patholo#ical cases involvin# networ/ failures. 7uppose $ calls A calls C calls * which will call bac/ to $, and while * is processin# its call, the lin/ from A to C #oes down, causin# A to try to obtain CDs services throu#h another party 6, which, as * would, calls bac/ to $. In such situations, $ may receive incomin# calls from both * and 6. Only the call from 6 is actually a potential for deadloc/. &hou#h this decision is subject to review. Page . DRAFT
uuid(99fcfe60-5260-101b-bbcb-00aa0021347a), pointer_default(unique) interface !b"ect#pc$a%e&'pe% ( )ifndef *!_+!_,-.!#&/ i0port 12t'pe%3idl14 )endif 55 t6e ob"ect id %pecifed doe% not e7i%t3 con%t un%i8ned lon8 #.9_:_,+;<=,*_!$>:9& ? 07@00101504 55 t6e ob"ect% e7porter %pecifed doe% not e7i%t3 con%t un%i8ned lon8 #.9_:_,+;<=,*_!A,* ? 07@00101514 55 t6e %et id %pecifed doe% not e7i%t3 con%t un%i8ned lon8 #.9_:_,+;<=,*_/:& ? 07@00101524 55 55 -ar%6allin8 con%tant%3 con%t un%i8ned int -/B=C=<D/_+!.,+D ? 44 con%t un%i8ned int -/B=C=<D/_/,-.=:,.,* ? @4 con%t un%i8ned int -/B=C=<D/_E::.<=,;: ? 164 555555555555555555555555555555555555555555555555555555555555 t'pedef t'pedef t'pedef t'pedef t'pedef t'pedef DF,* DF,* DF,* DF,* DF,* DF,* -,*4 !A,*4 !,*4 ,.,*4 /:&,*4 9,*4 55 55 55 55 55 55 -ac6ine ,dentifier !b"ect :7porter ,dentifier !b"ect ,dentifer ,nterface .ointer ,dentifier .in8 /et ,dentifier 9au%alit' ,dentifier
t'pedef #:CDF,* #:C,.,*4 t'pedef #:CDF,* #:C!A,*4 t'pedef #:CDF,* #:C!,*4 con%t un%i8ned %6ort 9!-_-<>!#_;:#/,!+ ? 14 con%t un%i8ned %6ort 9!-_-,+!#_;:#/,!+ ? 14 55 9o0ponent !b"ect -odel Ger%ion nu0ber t'pedef %truct ta89!-;:#/,!+ ( un%i8ned %6ort -a"or;er%ion4 55 -a"or Ger%ion nu0ber un%i8ned %6ort -inor;er%ion4 55 -inor Ger%ion nu0ber H 9!-;:#/,!+4 55 /&#,+D<##<I/ are t6e return t'pe for arra'% of net2orJ addre%%e%, 55 arra'% of endpoint% and arra'% of bot6 u%ed in 0an' !#.9 interface% con%t un%i8ned %6ort +9<*D_,._F*. con%t un%i8ned %6ort +9<9+_,._&9. con%t un%i8ned %6ort +9<*D_,.A con%t un%i8ned %6ort +9<9+_/.A con%t un%i8ned %6ort +9<9+_+$_+$ con%t un%i8ned %6ort +9<9+_*+:&_+/. con%t un%i8ned %6ort +9<=#.9 55 con%t un%i8ned %6ort -/K-/D ? ? ? ? ? ? ? 070@4 07074 070:4 07094 07124 07044 07104 ? 07014 55 noteL not a real to2er id3
55 t6i% i% t6e return t'pe for arra'% of %trin8 bindin8% or prot%eq% 55 u%ed b' 0an' !#.9 interface% t'pedef %truct ta8/&#,+D<##<I ( un%i8ned lon8 %iMe4 55 total %iMe of arra' 55 arra' of +F== ter0inated 2c6ar_t %trin8% 2it6 t2o +F==% at t6e end3 55 &6e fir%t 2ord of eac6 %trin8 i% t6e protocol ,* (aboGe) and t6e 55 re%t of t6e %trin8 i% t6e net2orJ addre%%[endpoint 3 [%iMe_i%(%iMe) H /&#,+D<##<I4 un%i8ned %6ort a2%M/trin8<rra'[ 4
55 fla8 Galue% for !$>#:C
DRAFT
Page /
con%t con%t con%t con%t con%t
un%i8ned un%i8ned un%i8ned un%i8ned un%i8ned
lon8 lon8 lon8 lon8 lon8
!$>#:C_/&<+*<#* ? !$>#:C_B<+*=:# ? !$>#:C_=!+D/&* ? !$>#:C_=!+DB*=# ? !$>#:C_9F/&!- ? 164
14 55 %tandard 0ar%6alled ob"ref 24 55 6andler 0ar%6alled ob"ref 44 55 lon8 for0 ob"ref @4 55 lon8 for0 6andler ob"ref 55 cu%to0 0ar%6alled ob"ref
55 fla8 Galue% for a /&*!$>#:C3 55 /6ould be an enu0 but *9: ,*= doe% not %upport %par%e enu0erator%3 55 !A#:/1 - !A#:/4 are re%erGed for t6e ob"ect e7porter% u%e onl', 55 ob"ect i0porter% %6ould i8nore t6e0 and not enforce -$N3 con%t un%i8ned lon8 /!#C_+!.,+D ? 14 55 .in8in8 i% not required con%t un%i8ned lon8 /!#C_!A#:/1 ? @4 55 re%erGed for e7porter con%t un%i8ned lon8 /!#C_!A#:/2 ? 164 55 re%erGed for e7porter con%t un%i8ned lon8 /!#C_!A#:/3 ? 324 55 re%erGed for e7porter con%t un%i8ned lon8 /!#C_!A#:/4 ? 644 55 re%erGed for e7porter 55 #e%erGed fla8 Galue% for a /&*!$>#:C3 con%t un%i8ned lon8 /!#C_C#::&B#:<*:* ? 24 55 %tandard ob"ect reference t'pedef %truct ta8/&*!$>#:C ( un%i8ned lon8 fla8%4 un%i8ned lon8 c#ef%4 ,.,* ipid4 !,* oid4 !A,* o7id4 H /&*!$>#:C4 55 .ro7' 0a' be u%ed on an' t6read
55 55 55 55 55
/&*!$>#:C fla8% count of reference% pa%%ed ipid of ,nterface oid of ob"ect 2it6 t6i% ipid o7id of %erGer 2it6 t6i% oid
55 for0at of a 0ar%6alled interface pointer t'pedef %truct ta8!$>#:C ( un%i8ned lon8 fla8%4 55 !$>#:C fla8% (%ee aboGe) [%2itc6_i%(fla8%), %2itc6_t'pe(un%i8ned lon8) ( [ca%e(!$>#:C_/&<+*<#*) /&*!$>#:C %td4 55 %tandard ob"ref [ca%e(!$>#:C_=!+D/&*) %truct ( /&*!$>#:C %td4 55 %tandard ob"ref /&#,+D<##<I %a#e%<ddr4 55 re%olGer addre%% H lon8%td4 [ca%e(!$>#:C_B<+*=:#) %truct ( /&*!$>#:C %td4 55 %tandard ob"ref 9=/,* cl%id4 55 9l%id of 6andler H 6andler4 [ca%e(!$>#:C_=!+DB*=#) %truct ( /&*!$>#:C %td4 55 %tandard ob"ref 9=/,* cl%id4 55 9l%id of 6andler (or DF,*_+F==) /&#,+D<##<I %a#e%<ddr4 55 re%olGer addre%% H lon86dlr4 [ca%e(!$>#:C_9F/&!-) ( %truct union
9=/,* cl%id4 55 9l%id of un0ar%6alin8 code un%i8ned lon8 %iMe4 55 %iMe of data t6at follo2% [%iMe_i%(%iMe), ref b'te Op*ata4 H cu%to04 H u_ob"ref4 H !$>#:C4 55 enu0eration of additional infor0ation pre%ent in t6e call pacJet3 55 /6ould be an enu0 but *9: ,*= doe% not %upport %par%e enu0erator%3
Page 0
DRAFT
con%t con%t con%t con%t con%t con%t
un%i8ned un%i8ned un%i8ned un%i8ned un%i8ned un%i8ned
lon8 lon8 lon8 lon8 lon8 lon8
,+C!_+F== ,+C!_=!9<= ,+C!_#:/:#;:*1 ,+C!_#:/:#;:*2 ,+C!_#:/:#;:*3 ,+C!_#:/:#;:*4
? ? ? ? ? ?
04 14 24 44 @4 164
55 55 55 55 55 55
no additional info in pacJet call i% local to t6i% 0ac6ine re%erGed for local u%e re%erGed for local u%e re%erGed for local u%e re%erGed for local u%e
55 :7ten%ion to i0plicit para0eter%3 t'pedef %truct ta8!#.9_:A&:+& ( DF,* id4 55 :7ten%ion identifier3 un%i8ned lon8 %iMe4 55 :7ten%ion %iMe3 [%iMe_i%((%iMeP7)QR7) b'te data[ 4 55 :7ten%ion data3 H !#.9_:A&:+&4 55 <rra' of e7ten%ion%3 t'pedef %truct ta8!#.9_:A&:+&_<##<I ( un%i8ned lon8 %iMe4 55 nu0 e7tent% [%iMe_i%((%iMeP1)QR1,), unique !#.9_:A&:+& OOe7tent4 55 e7tent% H !#.9_:A&:+&_<##<I4 55 i0plicit St6i%S pointer 26ic6 i% t6e fir%t [in para0eter on 55 eGer' !#.9 call3 t'pedef %truct ta8!#.9&B,/ ( 9!-;:#/,!+ Ger%ion4 55 9!- Ger%ion nu0ber un%i8ned lon8 fla8%4 55 ,+C! fla8% for pre%ence of ot6er data un%i8ned lon8 re%erGed14 55 %et to Mero 9,* cid4 55 cau%alit' id of caller 55 :7ten%ion%3 [unique !#.9_:A&:+&_<##<I Oe7ten%ion%4 H !#.9&B,/4 55 i0plicit St6atS pointer 26ic6 i% t6e fir%t [out para0eter on 55 eGer' !#.9 call3 t'pedef %truct ta8!#.9&B<& ( un%i8ned lon8 fla8%4 55 ,+C! fla8% for pre%ence of ot6er data 55 :7ten%ion%3 [unique !#.9_:A&:+&_<##<I Oe7ten%ion%4 H !#.9&B<&4 55 !# infor0ation a%%ociated 2it6 eac6 !A,*3 t'pedef %truct ta8!A,*_,+C! ( *K!#* d2&id4 55 t6read id of ob"ect e7porter *K!#* d2.id4 55 proce%% id of ob"ect e7porter ,.,* ipid#e0FnJno2n4 55 ,#e0FnJno2n ,.,* for ob"ect e7porter [unique /&#,+D<##<I Op%a4 55 protocol idS% and partial %trin8 bindin8% H !A,*_,+C!4
O$%RE&
$n O$%RE& is the data type used to represent an actual marshaled object reference. $n O$%RE& can either be empty or assume one of five variations, dependin# on the de#ree to which the object bein# marshaled uses the hoo/ architecture (I#ars/a(, etc." in the marshalin# infrastructure. &he O$%RE& structure is a union consistin# of a switch fla# followed by the appropriate data.
DRAFT
Page #
O#$%&'()T*ND*%D Contains one interface of an object marshaled in standard form. &he data that follows the switch fla# is a STDO$%RE& structure (described below". O#$%&'(+*NDL&% $ marshalin# of an object that wishes to use handler marshalin#. -or e(ample, an object wishes to be represented in client address spaces by a pro(y object that caches state. In this case, the class-specific information is just a standard reference to an interface pointer that the handler (pro(y object" will use to communicate with the ori#inal object. 7ee the ISt'#ars/a(Info interface.
Member
st' C(s+'
Type
STDO$%RE& C6SID
)emantic $ standard object reference used to connect to the source object. &he C6SID of handler to create in the destination client.
O#$%&'(LON,)TD $n interface marshaled on an object in lon# form. Contains a standard reference, alon# with a set of protocol se5uences and networ/ addresses that can be used to bind to an OXID resolver that is able to resolve the OXID in the STDO$%RE&. &his is useful when marshalin# a pro(y to #ive to another machine (a./.a. the middleman! case". &he marshalin# machine can specify the saResA''r for the resolver on the server machine so that the unmarshaler does not need to call the marshaler (middleman" bac/ to #et this information. -urther, the marshaler does not need to /eep the OXID in its cache beyond the lifetime of its own references in order to satisfy re5uests from parties that it just #ave the O$%RE& to.
Member
st' SaResA''r
Type
STDO$%RE& STRI4*ARRA7
)emantic $ standard object reference used to connect to the source object. &he resolver address.
O#$%&'(LON,+DL% Contains the same information as the handler case as well as the object resolver address. &his form is needed for the same reason O$%RE&26O4*STD is needed.
Member
st' C(s+' SaResA''r
Type
STDO$%RE& C6SID STRI4*ARRA7
)emantic $ standard object reference used to connect to the source object. &he class I* of the handler. &he resolver address.
O#$%&'(C-)TOM $ marshalin# of an object which supports custom marshalin#. &he Custom format #ives an object control over the representation of references to itself. -or e(ample, an immutable object mi#ht be passed by value, in which case the class-specific information would contain the objectDs immutable data. 7ee the I#ars/a( interface.
Member
c(s+' s+8e pData
Type
C6SID uns+,ne' (on, byte9
)emantic &he C6SID of the object to create in the destination client. &he si=e of the marshaled data provided by the source object and passed here in pData. &he data bytes that should be passed to I#ars/a())Un ars/a(Interface on a new instance of class c(s+' in order to initiali=e it and complete the unmarshal process.
'(DO$%RE&
$n instance of a STDO$%RE& represents a COM interface pointer that has been marshaled usin# the standard COM networ/ protocol. $ STDO$%RE& in #eneral can only be interpreted in the conte(t of an outstandin# O',C, for it may contain an OXID un/nown to the machine on which it is unmarshaled, and it is the only the machine which is ma/in# outstandin# call which is #uaranteed to be able to provide the bindin# information for the OXID. &he members and semantics of the STDO$%RE& structure are as follows%
Member
f(a,s
)emantic -la# values ta/en from the enumeration SOR&&6A*S. &hese are described below.
Page 11
DRAFT
Crefs Ip+' O+' Ox+'
&he number of reference counts on +p+' that bein# transferred in this marshalin#. &he IPID of the interface bein# marshaled. &he OID of the object to which +p+' corresponds. &he OXID of the server that owns this OID.
&he various SOR&6A*S values have the followin# meanin#s. &he SOR&2OXRESx bit fla#s are reserved for the object e(porterDs use only, and must be i#nored by object importers. &hey need not be passed throu#h when marshalin# an interface pro(y.
'la
SOR&24OPI4*
Val"e
:
SOR&2OXRES: SOR&2OXRES< SOR&2OXRES> SOR&2OXRES?
; := >< =?
Meanin &his OID does not re5uire pin#in#. -urther, all interfaces on this OID, includin# this IPID, need not be reference counted. ,in#in# and reference countin# on this object and its interfaces are still permitted, however, thou#h such action is pointless. 'eserved for e(porter. 'eserved for e(porter. 'eserved for e(porter. 'eserved for e(porter.
ORPC(#I'
In every 'e5uest ,*: that is an O',C, the body (C) case" or the stub data (CO case" which normally contains the marshaled ar#uments in fact be#ins with an instance of the ORPCTHIS structure. &he marshaled ar#uments of the COM interface invocation follow the ORPCTHIS. thus, viewed at the *C6 ',C perspective, the call has an additional first ar#ument. &he ORPCTHIS is padded with =ero-bytes if necessary to achieve an overall si=e that is a multiple of ei#ht bytes. thus, the remainin# ar#uments are as a whole ei#ht byte ali#ned. $s in re#ular calls, the causality id must be propa#ated. If $ calls Co puteP+ on A, A calls Re(ease on C (which #ets converted to Re Re(ease", and C calls A'' on $, $ will see the same causality id that it called A with.
Member
@ers+on
Type
CO#3ERSIO4
f(a,s reser@e' c+' extens+ons
uns+,ne' (on, uns+,ne' (on, CID ORPC2EXTE4T2ARRA79
)emantic &he version number of the COM protocol used to ma/e this particular O',C. &he initial value will be 1.1. 6ach pac/et contains the senderDs major and minor O',C version numbers. &he clientDs and serverDs major versions must be e5ual. Aac/ward compatible chan#es in the protocol are indicated by hi#her minor version numbers. &herefore, a serverDs minor version must be #reater than or e5ual to the clientDs. However, if the serverDs minor version e(ceeds the clientDs minor version, it must return the clientDs minor version and restrict its use of the protocol to the minor version specified by the client. $ protocol version mismatch causes the RPC2E23ERSIO42#IS#ATCH ORPC fault to be returned. -la# values ta/en from the enumeration ORPCI4&O&6A*S. &hese are elaborated below. Must be set to =ero. &he causality id of this O',C. 7ee comments below. &he body e(tensions, if any, passed with this call. Aody e(tensions are *UID-ta##ed blobs of data which are marshaled as an array of bytes. 6(tensions are always marshaled with initial ei#ht byte ali#nment. Aody e(tensions which are presently defined are described below.
&he various ORPCI4&O&6A*S have the followin# meanin#s.

'la
I4&O24U66 I4&O26OCA6 I4&O2RESER3ED: I4&O2RESER3ED< I4&O2RESER3ED> I4&O2RESER3ED?
Implementations may use the local and reserved fla#s to indicate any e(tra information needed for local calls. 4ote that if t/e I4&O26OCA6 bit is not set and any of the other bits are set then the receiver should return a fault. Comment!
DRAFT Page 11 Cop!right " 1##5 Micro$oft Corporation All Right$ Re$er%e&
Meanin (4ot a real fla#. Merely a defined constant indicatin# the absence of any fla# values." &he destination of this call is on the same machine on which it ori#inates. &his value is never to be specified in calls which are not in fact local. If I4&O26OCA6 is set, then reserved for local use. otherwise, reserved for future use. If I4&O26OCA6 is set, then reserved for local use. otherwise, reserved for future use. If I4&O26OCA6 is set, then reserved for local use. otherwise, reserved for future use. If I4&O26OCA6 is set, then reserved for local use. otherwise, reserved for future use.
&he c+' field contains the causality id. 11 6ach time a client ma/es a call, a new causality id is #enerated. If a server ma/es a call while processin# a re5uest from a client, the new call must have the same causality id. &his allows simple servers to avoid wor/in# on more then one thin# at a time (for e(ample $ calls A calls $ a#ain, meanwhile C tries to call $ with a new causality id". It tells the server that he is bein# called because he as/ed someone to do somethin# for him. &here are several interestin# e(ceptions. &he causality id for aybe and +'e potent calls must be set to CID24U66. If a server ma/es a O',C call while processin# such a call, a new causality id must be #enerated.
In the face of networ/ failures, the same causality id may end up in use by two independent processes at the same time. If $ calls A calls C calls * and C fails, both A and * can independently, simultaneously ma/e calls to 6 with the same causality id. &he extens+ons field contains e(tensions to the channel header. &wo are currently defined for MicrosoftDs implementation of this protocol (described below". Other implementations may define their own e(tensions with their own ::I*s. Implementations should s/ip over e(tensions they do not reco#ni=e or wish to support. 4ote that in order to force the ORPCTHIS header to be < byte ali#ned an even number of e(tensions must be present and the si=e of the e(tension data must be a multiple of <.
ORPC(#)(
In every 'esponse ,*: that is an O',C, the body (C) case" or the stub data (CO case" which normally contains the marshaled output parameters in fact be#ins with an instance of the ORPCTHAT structure. &he marshaled output parameters of the COM interface invocation follow the ORPCTHAT. thus, viewed at the *C6 ',C perspective, the call has an additional output parameters. &he ORPCTHAT is padded with =erobytes if necessary to achieve an overall si=e that is a multiple of ei#ht bytes. thus, the remainin# output parameters as a whole ei#ht byte ali#ned.
Member
f(a,s extens+ons
Type
uns+,ne' (on, ORPC2EXTE4T2ARRA79
)emantic -la# values ta/en from the enumeration ORPCI4&O&6A*S. &hese are elaborated above. &he body e(tensions, if any, returned by this call. Aody e(tensions are *UID-ta##ed blobs of data which are marshaled as an array of bytes. 6(tensions are always marshaled with initial ei#ht byte ali#nment.
Debug Infor*ation $od! Extension

&his e(tension aids in debu##in# O',C. In particular it is desi#ned to allow sin#le steppin# over an O',C call into the server and out of the server into the client. 7ee JJ '6-6'64C6 KK for more details. &his e(tension is identified by the UUID Af:f:B=;50?'<a0::ce0a==a055<5af=eC<f?D.
Extended Error Info $od! Extension

&he e(tended error information body e(tension conveys e(tended error information concernin# the ori#inal root cause of a error bac/ to a caller can deal with it. It is intended that this error information is suitable for displayin# information to a human bein# who is the user. this information is not intended to be the basis for lo#ic decisions in a piece of client code, for doin# so couples the client code to the implementation of the server. 'ather, client code should act semantically only on the information returned throu#h the interface that it invo/es. 7ee also the ISupportErrorInfo, IErrorInfo, and ICreateErrorInfo interfaces. &his e(tension is identified by the UUID f:f:B=;:0?'<a0::ce0a==a055<5af=eC<f?. It is only semantically useful in 'esponse and -ault ,*:s. &here are three variations of the error information. &he first of these can be used in a local conte(t, where a" the server /nows it can reliably specify a path name to a file that can in fact be understood by the client, and b" the server /nows the lan#ua#e of interest to the client. &his first variation specifies the followin# members%
Member
"s8ErrorStr+n, "s8He(p&+(e u(He(pContext
11
De!cription $n error strin# suitable for display to a human user. $ path to a help file that can #ive additional information concernin# the error. $ help conte(t topic within that help file.
In several early specifications the term logical threa& i& was used instead of causality id. &he name was chan#ed because the term lo#ical thread id implies a sin#le threaded model that is not #uaranteed. Page 1' DRAFT
&he second variation is suitable for use in remote situations where one or the other of the re5uirements of the use of the first variation cannot be upheld. &his second variation specifies the followin# members%
Member
uu+'ErrorSe ant+c u(ErrorSe ant+c cbData pbData "s8ErrorStr+n,
(c+'ErrorStr+n,
De!cription $ UUID si#nifyin# the semantic of the error. $ four-byte 5uantity that 5ualifies the error semantic. &he semantics of these four bytes are completely determined by the uu+'ErrorSe ant+c. &he si=e of the data passed in pbData. *ata associated with the error marshaled as an array of bytes. &he interpretation of these bytes is #overned by the uu+'ErrorSe ant+c. $n error strin# suitable for display to a human user. &his is in fact of somewhat little use, as the server returnin# the error can usually only #uess as to the appropriate lan#ua#e in which to form this strin#. However, the ability to pass such as strin# as a last resort is provided here. &he locale conte(t in which the error strin#, if any, is formed. )ocale constants are as in the Microsoft +in0; $,I.
&he third variation allows for e(tensibility of the error information bein# passed. It specifies an object reference (an O$%RE&". In practice, this reference most always contains a custom marshaled object, thou#h this is not re5uired.
.%em-nknown inter/ace
&he IRe Un!no"n interface is used by remote clients for manipulatin# reference counts on the IPIDs that they hold and for obtainin# additional interfaces on the objects on which those IPIDs are found. &his interface is implemented by the COM OBI* object! associated with each OXID (nb. not each Object 6(porter". &he IPID for the IRe Un!no"n interface on this object is returned from IObjectExporter))Reso(@eOx+'. see below. $n OXID object need never be pin#ed. its interfaces (this IPID included" need never be reference counted. IRe Un!no"n is specified as follows (RE#U4E.ID6"%
55P------------------------------------------------------------------------55 55 -icro%oft Kindo2% 55 9op'ri86t (9) -icro%oft 9orporation, 1992 - 19953 55 55 CileL re0unJ3idl 55 55 &6e re0ote Ger%ion of ,FnJno2n3 !nce in%tance of t6i% interface e7i%t% 55 per !A,* (26et6er an !A,* repre%ent% eit6er a t6read or a proce%% i% 55 i0ple0entation %pecific)3 &6i% interface i% pa%%ed alon8 durin8 !A,* 55 re%olution3 ,t i% u%ed b' client% to quer' for ne2 interface%, 8et 55 additional reference% (for 0ar%6allin8), and relea%e out%tandin8 55 reference%3 55 55P------------------------------------------------------------------------[ ob"ect, uuid(99fcff2@-5260-101b-bbcb-00aa0021347a) i0port 1unJn2n3idl14 interface ,#e0FnJno2n L ,FnJno2n ( 55 return %tructure fro0 a T, call t'pedef %truct ta8#:-T,#:/F=& ( B#:/F=& 6#e%ult4 55 re%ult of call /&*!$>#:C %td4 55 data for returned interface H #:-T,#:/F=&4 B#:/F=& #e0Tuer',nterface ( [in ,.,* ipid, 55 interface to T, on [in un%i8ned lon8 c#ef%, 55 count of <dd#ef% reque%ted for eac6 interface [in un%i8ned %6ort c,id%, 55 count of ,,*% t6at follo2 [in, %iMe_i%(c,id%) ,,* Oiid%, 55 ,,*% to quer' for [out, %iMe_i%(,c,id%) #:-T,#:/F=& OOppT,#e%ult% 55 re%ult% returned
DRAFT
Page 1,
)4 55 %tructure pa%%ed to <dd#ef5#elea%e to %pecif' interface and count of 55 reference% to <dd5#elea%e3 t'pedef %truct ta8#:-,+&:#C<9:#:C ( ,.,* ipid4 55 ipid to <dd#ef5#elea%e un%i8ned lon8 c#ef%4 55 nu0ber of ref% to add5relea%e H #:-,+&:#C<9:#:C4 B#:/F=& #e0<dd#ef ( [in un%i8ned %6ort c,nterface#ef%, [in, %iMe_i%(c,nterface#ef%) #:-,+&:#C<9:#:C ,nterface#ef%[ )4 B#:/F=& #e0#elea%e ( [in un%i8ned %6ort c,nterface#ef%, [in, %iMe_i%(c,nterface#ef%) #:-,+&:#C<9:#:C ,nterface#ef%[ )4
Comment! 'eferences are /ept per interface rather then per object. .%em-nknown::%em0"ery.nter/ace H'67:)& I'em:n/nown%%'emEueryInterface(ipid, cIids, c'efs, iids, ppEI'esults" QueryInterface for and return the result thereof for =ero or more interfaces from the interface behind the IPID +p+'. +p+' must desi#nate an interface derived from IUn!no"n (recall that all remoted interfaces must derive from IUn!no"n". &he QueryInterface ca((s on the object that are used to service this re5uest are conducted on this interface instance, not any other IUn!no"n instance that the object may happen to have. &hus if the client calls I&oo0FQueryInterface rather then pIUn!no"n0FQueryInterface, Re QueryInterface will also call QueryInterface on I&oo. *r "ment Type De!cription
+p+' cRefs cI+'s ++'s ppQIResu(ts Return Value S2OE IPID RE&C4T USHORT IID9 RE#QIRESU6T99
&he interface on an object from whom more interfaces are desired. &he number of references sou#ht on each of the returned II*s. &he number of interfaces bein# re5uested. &he list of IIDs that name the interfaces sou#ht on this object. &he place at which the array of the results of the various QueryInterface calls are returned.
Meanin 7uccess. $n attempt was made to retrieve each of the re5uested interfaces from the indicated object. that is, QueryInterface was actually invo/ed for each IID. One or more ar#uments (li/ely +p+'" were invalid. 4o result values are returned. $n unspecified error occurred. 4o result values are returned.
E2I43A6IDAR* E2U4EXPECTED
&he RE#QIRESU6T structure contains the followin# members%

Member
/Resu(t st'
Type
HRESU6T STDO$%RE&
)emantic &he result code from the QueryInterface call made for the re5uested IID. &he data for the returned interface. 4ote that if /Resu(t indicates failure then the contents of STDO$%RE& are undefined .
Page 1-
DRAFT
.%em-nknown::%em*dd%e/ H'67:)& I'em:n/nown%%'em$dd'ef(cInterface'efs, r#'efs" *r "ment Type De!cription

cInterfaceRefs r,Refs
&he si=e of the r,Refs array. RE#I4TER&ACERE& $n array of IPID1 cRefs pairs, cInterfaceRefs (ar,e. 6ach IPID indicates an interface mana#ed by this OXID on whom more reference counts are sou#ht. &he correspondin# reference count (cRefs", which may not be =ero (and thus is one or more", indicates the number of reference counts sou#ht on that IPID.
uns+,ne' s/ort
Return Value S2OE E2I43A6IDAR*
E2U4EXPECTED
Meanin 7uccess. $n attempt was made to retrieve each of the re5uested interfaces. One or more of the IPIDs indicated were not in fact mana#ed by this OBI*, or one or more of the re5uested reference counts was =ero. None of the re5uested reference counts have been #ranted to the caller. the call is a no-op. $n unspecified error occurred. It is un/nown whether any or all of the re5uested reference counts have been #ranted.
Comment! $ useful optimi=ation is for a caller to Re A''Ref more than needed. +hen a process receives an out marshaled interface, it receives one reference count. If the process wishes to pass that interface as an out parameter, it must #et another reference to pass alon#. Instead, the process (or middleman" should #et a lar#e number of references. &hen if the interface is passed out multiple times, no new remote calls are needed to #ain additional references. $ marshaler may optionally specify more than one reference in the STDO$%RE& when marshalin# an interface. &his allows the middle man case to pre-fill its cache of references without ma/in# an e(tra Re A''Ref call. &he number of references passed is always specified in the STDO$%RE& field. Obtain 'elease and ownership #rant ownership of one or tomore the caller reference of one counts or more on one reference or more counts IPIDson mana#ed one or more by the IPIDs correspondin# mana#ed by the OXID correspondin# . OXID. .%em-nknown::%em%elea!e H'67:)& I'em:n/nown%%'em'elease(cInterface'efs, r#'efs" *r "ment Type De!cription
cInterfaceRefs r,Refs
&he si=e of the r,Refs array. RE#I4TER&ACERE& $n array of IPID, cRefs pairs, cInterfaceRefs lar#e. 6ach IPID indicates an interface mana#ed by this OXID on whom more reference counts are bein# returned. &he correspondin# reference count, which may not be =ero (and thus is one or more", indicates the number of reference counts returned on that IPID.
USHORT
Return Value S2OE E2I43A6IDAR*
Meanin 7uccess. $n attempt was made to retrieve each of the re5uested interfaces. One or more of the IPIDs indicated were not in fact mana#ed by this OXID, or one or more of the re5uested reference counts was =ero. None of the offered reference counts have been accepted by the server. the call is a no-op. $n unspecified error occurred. It is un/nown whether any or all of the offered reference counts have been accepted.
E2U4EXPECTED
The Object &1porter

6ach machine that supports the COM networ/ protocol supports a one-per-machine service /nown as the machineDs LObject 6(porter.D Communication with an Object 6(porter is via a *C6 ',C, not an O',C. &o ensure connectivity, the Object 6(porter resides at well-/nown endpoints. It is proposed that the Object 6(porter either (1" ma/e use of the same endpoints allocated for the *C6 ',C 6ndpoint Mapper (listed below"1;, implyin# typically that these services are written within the same process on a #iven machine, or
1;
7ee 8C$6 ',C9, $ppendi( H, p @10. Page 15 Cop!right " 1##5 Micro$oft Corporation All Right$ Re$er%e&
DRAFT
Protocol )trin Name2!3

nca',2+p2u'p1 +p ncacn2+p2tcp nca',2+px ncacn2spx ncacn2nb2nb ncacn2nb2tcp ncacn2np ncacn2'net2nsp ncacn2os+2'na nca',2''s1 ''s nca(rpc
De!cription C) over :*,HI, CO over &C,HI, C) over I,B CO over 7,B CO over 4etAIO7 over 4etA6:I CO over 4etAIO7 over &C,HI, CO over 4amed ,ipes CO over *6C4et 4etwor/ 7ervices ,rotocol (*6Cnet ,hase IM" CO over Open 7ystems Interconnection (*6C4et ,hase M" C) over *omain *ata#ram 7ervice )ocal procedure call
Object &1porter &nd Point

T$D T$D T$D T$D T$D T$D T$D T$D T$D T$D 4HA
&ndpoint Mapper &nd Point

:>G :>G not yet (+ste' not yet (+ste' not yet (+ste' :>G not yet (+ste' =B =B :< 4HA
Table 45 Object &1porter 6ell7known &ndpoint! alternately and less preferably (;" that the Object 6(porter reside at a different set of well-/nown endpoints &A*. &he Object 6(porter performs several services% It caches and returns to clients when as/ed the strin# bindin#s necessary to connect to e(ported objects for which this machine is it either itself a client or is the server.
OXIDs
of
It receives pin#s from remote client machines to /eep its own objects alive. &hese services are carried out throu#h an ',C interface (not a COM interface" /nown as IObjectExporter. $n Object 6(porter may be as/ed for the information re5uired to connect to one of two different /inds of OXIDs, either the OXIDs associated with its own objects, or the OXIDs associated with objects for which it itself is a client, and which it has passed on to a second client machine. &his second case, where one marshals an object from one client machine to a second, is collo5uially referred to the middleman ! case. In the middleman case, the e(porter is re5uired to retain the connection information associated with the OXIDs that it passes on until it is certain that that the second client machine no lon#er needs them. More on this below. IObjectExporter interface is defined as follows (OAG6B.I*)"%
55P------------------------------------------------------------------------55 55 -icro%oft Kindo2% 55 9op'ri86t (9) -icro%oft 9orporation, 1992 - 19953 55 55 CileL ob"e73idl 55 55 /'nop%i%L ,nterface i0ple0ented b' ob"ect e7porter%3 55 55 &6i% i% t6e interface t6at need% to be %upported b' 6o%t% t6at e7port 55 ob"ect%3 !nl' one in%tance of t6i% interface can be e7ported b' t6e 6o%t3 55 55 <n ob"ect e7porter need% to be able toL 55 13 return %trin8 bindin8% t6at can be u%ed to talJ to ob"ect% it 55 6a% e7ported 55 23 receiGe pin8% fro0 ob"ect i0porter% to Jeep t6e ob"ect% aliGe 55 55-------------------------------------------------------------------------[ uuid(99fcfec4-5260-101b-bbcb-00aa0021347a), pointer_default(unique) interface ,!b"ect:7porter ( i0port 1oba%e3idl14 55 -et6od to 8et t6e protocol %equence%, %trin8 bindin8% and 0ac6ine id 55 for an ob"ect %erGer 8iGen it% !A,*3 [ide0potent ( error_%tatu%_t #e%olGe!7id
Page 1.
DRAFT
[in [in [in [in,
6andle_t 6#pc, !A,* Op!7id, un%i8ned %6ort c#eque%ted.rot%eq%, ref, %iMe_i%(c#eque%ted.rot%eq%) un%i8ned %6ort ar#eque%ted.rot%eq%[ , [out, ref -,* Op0id, [out, ref /&#,+D<##<I OOp%a!7id$indin8%, [out, ref ,.,* Opipid#e0FnJno2n )4 55 55 55 55 /i0ple pin8 i% u%ed to pin8 a /et3 9lient 0ac6ine% u%e t6i% to infor0 t6e ob"ect e7porter t6at it i% %till u%in8 t6e ite0% in%ide t6e %et3 #eturn% /_&#F: if t6e /et,d i% Jno2n b' t6e ob"ect e7porter, /_C<=/: if not3
[ide0potent error_%tatu%_t /i0ple.in8 ( [in 6andle_t 6#pc, [in /:&,* Op/et,d )4 55 9o0ple7 pin8 i% u%ed to create %et% of !,*% to pin83 &6e 26ole %et 55 can %ub%equentl' be pin8ed u%in8 /i0ple.in8, t6u% reducin8 net2orJ 55 traffic3 [ide0potent error_%tatu%_t 9o0ple7.in8 ( [in 6andle_t 6#pc, [in /:&,* Op/et,d, [in un%i8ned %6ort /equence+u0, [in un%i8ned %6ort /et.in8.eriod, [in un%i8ned %6ort /et+u0.in8%&o&i0eout, [out un%i8ned %6ort Op#eq/et.in8.eriod, [out un%i8ned %6ort Op#eq/et+u0.in8%&o&i0eout, [in un%i8ned %6ort c<dd&o/et, [in un%i8ned %6ort c*elCro0/et, [in, unique, %iMe_i%(c<dd&o/et) DF,* <dd&o/et[ , [in, unique, %iMe_i%(c*elCro0/et) DF,* *elCro0/et[ )4
55 add t6e%e !,*% to t6e %et 55 re0oGe t6e%e !,*% fro0 t6e %et
.Object&1porter::%e!olveO1id
[ide0potent error_%tatu%_t #e%olGe!7id ( [in 6andle_t hRpc, [in !A,* OpOxid, [in un%i8ned %6ort cRequestedProtseqs, [in, ref, %iMe_i%(c#eque%ted.rot%eq%) un%i8ned %6ort arRequestedProtseqs[ , [out, ref -,* Opmid, [out, ref /&#,+D<##<I OOpsaOxidBindings, [out, ref ,.,* OpipidRemUnknown )4 'eturn the strin# bindin#s necessary to connect to a #iven OXID object.
On entry, arReIueste'ProtseIs contains the protocol se5uences the client is willin# to use to reach the server. &hese should be decreasin# order of protocol preference, with no duplicates permitted. )ocal protocols (such as ncalrpc!" are not permitted. On e(it, psaOx+'$+n'+n,s contains the strin# bindin#s that may be used to connect to the indicated OXID. if no such protocol bindin#s e(ist which match the re5uested protocol se5uences, 4U66 may be returned. &he returned strin# bindin#s are in decreasin# order of preference of the server, with duplicate strin# bindin#s permitted (and not necessarily of the same preferential priority", thou#h of course duplicates are of no utility. )ocal protocol se5uences may not be present. however, protocol se5uences that were not in the set of protocol se5uences re5uested by the client may be. &he strin# bindin#s returned need not contain endpoints. the endpoint mapper will be used as usual to obtain these dynamically. If a Reso(@eOx+' call is received for which the recipient Object 6(porter is a middleman, the action re5uired of the middleman depends on how the ordered list of re5uested protocol se5uences ( arReIueste'ProtseIs" relate to lists of protocol se5uences previously /nown by the middleman to have been previously re5uested
DRAFT Page 1/ Cop!right " 1##5 Micro$oft Corporation All Right$ Re$er%e&
of the server. If the list of re5uested protocol se5uences is a (perhaps non-proper" subset in order of a protocol se5uence list previously re5uested of the server, then the correspondin# cached strin# bindin#s may be returned immediately to the caller without actually communicatin# with the server. Otherwise, the actual psaReIueste'ProtseIs must be forwarded to the server, and the returned strin# bindin#s propa#ated bac/ to the client. In such cases, it behooves the middleman to cache the returned strin# bindin#s for use in later calls. In order to support the middleman case, Object 6(porters are re5uired to remember the OXID mappin# information for remote OXIDs they have learned for some period of time beyond when they themselves have released all references to objects of this OXID. )et t be the full time-out period (pin# period number of pin#s to time-out" for some OID (any OID" for which this Object 6(porters is a client and which resides in OXID. &hen the Object 6(porter must /eep the bindin# information for OXID for at least an amount of time t followin# the release of a the local reference to any object in OXID.10 'eturned throu#h p +' is an identifier that uni5uely identifies the machine. Clients can use this to learn which OXIDs are collocated on the same machine, and thus which OIDs may be appropriately #rouped to#ether in pin# sets (see Co p(exP+n,". &he machine identifier is #uaranteed not to chan#e so lon# as there are remote references to objects on the machine which remain valid. &hus, specifically, the machine id may chan#e as the machine reboots. Reso(@eOx+' also informs the caller of the IPID of the OXID object associated with this OXID. *r "ment Type De!cription
/Rpc pOx+' /an'(e2t OXID9
cReIueste'ProtseIs arReIueste'ProtseIs
uns+,ne' s/ort uns+,ne' s/ort-.
p +' psaOx+'$+n'+n,s p+p+'Re Un!no"n
#ID9 STRI4*ARRA799 IPID9
$n ',C bindin# handle used to ma/e the re5uest. &he OXID for whom strin# bindin#s are re5uested. . &he OBI* may or may not represent a process on the machine that receives the Reso(@eOx+' call &he number of protocol se5uences re5uested. arReIueste'ProtseIs must be initiali=ed with all the protocol idDs the client is willin# to use to reach the server. It cannot contain local protocol se5uences. &he object e(porter must ta/e care of local loo/ups privately. &he protocol se5uences are in order of preference or random order. 4o duplicates are allowed. 7ee the )a=y :se ,rotse5 section for more details. &he machine identifier associated with OXID. &he strin# bindin#s supported by this OXID, in preferential order. 4ote that these are :nicode strin#s. &he IPID to the IRe Un!no"n interface the OXID object for this OXID.
Return Value S2OE RPC2E2I43A6ID2O$%ECT RPC2E2I43A6ID2OXID RPC2E2SER3ER2DIED E2OUTO&#E#OR7 E2U4EXPECTED
Meanin 7uccess. &he re5uested information was returned. &his OXID is un/nown to this Object 6(porter, and thus no information was returned.
$n unspecified error occurred. 7ome of the re5uested information may not be returned.
Comment! Since the object exporter ages string bindings and discards them, object references are transient things. They are not meant to be stored in files or otherwise kept persistently. The preferred method of storing persistent references will depend on the activation models available. On platforms that support them, monikers should be used for any persistent reference. In any case, well known object references can be constructed from well known string bindings, IPIDs and OIDs. Conversely, since object references are aged, it is the responsibility of each client to unmarshal them and begin pinging them in a timely fashion.
10
&his time-out period does not guarantee that OBI* information will not be discarded before clients may need it, but is a very #ood heuristic, and indeed better than a hard-coded time-out value. Page 10 DRAFT
The basic use of the Reso(@eOx+' method is to translate an OXID to string bindings. Put another way, this method translates an opaque process and machine identifier to the information needed to reach that machine and process. There are four interesting cases: looking up an OXID the first time an interface is unmarshaled on a machine, looking up an OXID between a pair of machines that already have connections, looking up an OXID from a middleman, and looking up string bindings with unresolved endpoints (lazy use protseq). Another interesting topic is garbage collection of stored string binding vectors. Look"p #etween 'riend! OX C Process D OX E Process F Process G call F pass out ref to G receive out ref to G ask local OX to resolve OXID G ask OX E to resolve OXID G look up G and return Gs endpoints. Construct and cache string binding vector for G return results to D ready to call G directly &he case of a loo/up between two machines that have already established communication is the easiest. In this scenario there are two machines, $ and A. ,rocess * already has an interface pointer to process -. Object e(porter C already /nows the strin# bindin#s for object e(porter 6 and process -, but not process N. Object e(porter 6 /nows the strin# bindin#s for all the servers on its machine, i.e. processes - and N. ,rocess * calls process - and #ets a reference to process N. 7ince process * has never seen the OXID for N before, it as/s its local object e(porter to resolve N. ,rocess * also has to tell object e(porter C where it #ot the reference from, in this case, process -. Object e(porter C does not reco#ni=e the OBI* N. However it does reco#ni=e the OXID - and /nows the object e(porter 6 is on the same machine as process -. 7o OB C calls Reso(@eOx+' on OB 6. OB 6 reco#ni=es N and passes the strin# bindin#s bac/ to OB C with the machine id A. OB C caches this information so that if * ever #ets a reference from N, it /nows who to as/ to resolve that reference. My 'ir!t Look"p &he previous e(ample assumes that OB C already /nows about OB 6 and process * is already tal/in# to process -. 7ettin# up the first connection between * and - (as well as C and 6" is a tric/y business /nown as activation. O',C as described in this specification does not include activation models. &hus different vendors may have different activation models. However there is one basic form of activation shared by all O',C. If two processes can communicate via *C6 ',C, they can pass lon# standard object references. +hile this is not e(pected to be a common form of activation, it is a simple one that should certainly wor/ across all O',C implementations. &hus if * and 6 have established *C6 ',C (or raw ',C" communication, they can bootstrap O',C communication as follows. OB C ,rocess * OB 6 ,rocess re#ister endpoints and OXID for call - with raw ',C pass an out ref to pass IID as additional parameter tell C the OXID2I4&O and
DRAFT Page 1# Cop!right " 1##5 Micro$oft Corporation All Right$ Re$er%e&
for -. Include networ/ address(es".

#ID
compute the strin# bindin#s for OB 6 from as/ 6 to resolve - to #et machine id and endpoints for return endpoints and machine id ready to call - via O',C &his e(ample points out that there has to be a local interface between processes and the local object e(porter. Middleman Look"p &he ne(t case shows how loo/up wor/s between multiple machines. 7uppose that 6 has a reference to N and N has a reference to I. 7imilarly, * /nows about - and N and - /nows about H and I. +hat happens if N passes a reference to I over to 6O OX D Process E OX F Process G OX H Process I call G return a long reference to I ask D to lookup I Since its a long ref to I call Reso(@eOx+' on H. Return endpoints to I Compute string bindings to I from endpoints and network addresses. return string bindings to E ready to call I 4ote that when process N returned a reference to I, it used he lon# form of the O$%RE& which includes the protocol idDs and networ/ addresses of the OXID resolver for process I (in this e(ample, the addresses for OB H". &his would results in OB * callin# OB H directly, rather than needin# to call OB -. &he advanta#e of this is that if no references to process I needed by OB -, it could remove it from its OXID cache at any time, rather than /eepin# it around at least until OB * has had a chance to call it bac/ to resolve OXID I. La8y -!e Prot!e9 In a homogeneous network, all machines communication via the same protocol sequence. In a heterogeneous network, machines may support multiple protocol sequences. Since it is often expensive in resources to allocate endpoints ( RpcSer@erUseProtseI) for all available protocol sequences, ORPC provides a mechanism where they may be allocated on demand. To implement this extension fully, there are some changes in the server. However, changes are optional. If not implemented, ORPC will still work correctly if less optimally in heterogeneous networks. There are two cases: the server implements the lazy use protocol or it does not.
Page '1
DRAFT
If the server is using the lazy use protseq protocol, the use of Reso(@eOx+' is modified slightly. When the client OX calls the server OX, it passes the requested protseq vector. If none of the requested protseqs have endpoints allocated in the server, the server OX performs some local magic to get one allocated. If the server does not implement the lazy use protseq protocol, then all protseqs are registered by the server and contain complete endpoints. However, if they are not, the endpoint mapper can be used to forward calls to the server. This requires that all server IIDs are registered in the endpoint mapper. It also allows a different lazy use protseq mechanism. The endpoint mapper can perform some local magic to force the server to allocate an endpoint. This is less efficient since no OXs ever learn the new endpoints. The client will always pass in a vector of requested protseqs which the server can ignore if it does not implement the lazy use protseq protocol. * in )trin #indin ! Each object exporter must keep all the string bindings for references to remote machines as well as string bindings for all processes that are ORPC servers on its machines. However, unless the middle man marshaler always marshals proxy interfaces using the long form O$%RE&, string bindings cannot be discarded as soon as remote references are. In the middleman example above, a process could pass out a reference to a remote object and immediately release any remaining references to that remote object. When the poor client called back to translate the OXID, the string bindings would be gone. To deal with that case, the object exporter must keep the string binding/ OXID translation for one full time-out period (round up if the release occurs in the middle of a ping period) after the last local reference is released. A time-out period is the number of pings times the ping period. .Object&1porter::)implePin
[ide0potent error_%tatu%_t /i0ple.in8 ( [in 6andle_t hRpc, [in /:&,* OpSetId )4
,in#s provide a mechanism to #arba#e collect interfaces. If an interface has references but is not bein# pin#ed, it may be released. Conversely, if an interface has no references, it may be released even thou#h it has recently been pin#ed. S+ p(eP+n, just pin#s the contents of a set. &he set must be created with Co p(exP+n, (see below". ,in# a set, previously created with IObjectExporter))Co p(exP+n,, of OIDs owned by this Object 6(porter. 4ote that neither IPIDs nor OIDs may be pin#ed, only e(plicitly created SETIDs. *r "ment Type De!cription
/Rpc pSetI' /an'(e2t SETID9
$n ',C bindin# handle used to ma/e the re5uest. $ SETID previously created with IObjectExporter))Co same Object 6(porter.
p(exP+n, on
this
Return Value S2OE RPC2E2I43A6ID2SET E2U4EXPECTED
Meanin 7uccess. &he set was pin#ed. &his SETID is un/nown to this Object 6(porter, and thus the pin# did not occur. $n unspecified error occurred. It is not /nown whether the pin# was done or not.
.Object&1porter::Comple1Pin
[ide0potent error_%tatu%_t 9o0ple7.in8 ( [in 6andle_t hRpc, [in /:&,* OpSetId, [in un%i8ned %6ort SequenceNum, [in un%i8ned %6ort SetPingPeriod, [in un%i8ned %6ort SetNumPingsToTimeout, [out un%i8ned %6ort OpReqSetPingPeriod, [out un%i8ned %6ort OpReqSetNumPingsToTimeout, [in un%i8ned %6ort cAddToSet, [in un%i8ned %6ort cDel romSet, [in, unique, %iMe_i%(c<dd&o/et) DF,* AddToSet[ , [in, unique, %iMe_i%(c*elCro0/et) DF,* Del romSet[ )4
DRAFT
Page '1
,in# a pin# set. Optionally, add and H or remove some OIDs from the set. Optionally, adjust the pin# timin# parameters associated with the set. $fter a set is defined, a S+ p(eP+n, will mar/ the entire contents of the set as active. $fter a set is defined, S+ p(eP+n, should be used to pin# the set. Co p(exP+n, need only be used to adjust the contents of the set (or the time-out". ,in# set ids (SETIDs" are allocated unilaterally by a client Object 6(porter. &he client Object 6(porter then communicates with the server Object 6(porter to add (and later remove" OIDs from the pin# set. Clients must ensure the SETIDs pin#ed at a #iven server are uni5ue over all of that serverDs clients. &hus, the client must only use SETIDs that it /nows not to be in use as SETIDs by other clients on that server. (In practice, clients allocate SETIDs as #lobally uni5ue". $ client may use as many sets as it li/es, thou#h usin# fewer sets is more efficient. 6ach OID owned by a server Object 6(porter may be placed in =ero or more pin# sets by the various clients of the OID. &he client owner of each such set will set a pin# period and a pin# time-out count for the set, thus determinin# an overall time-out period for the set as the product of these two values. &he time-out period is implicitly applied to each OID contained in the set and to future OIDs that mi#ht add be added to it. &he server Object 6(porter is responsible for ensurin# that an OID that it owns does not e(pire until at least a period of time t has elapsed without that OID bein# pin#ed, where t is the ma(imum time-out period over all the sets which presently contain the #iven OID, or, if OID is not presently in any such sets but was previously, t is the time-out period for the last set from which OID was removed at the instant that that removal was done.1> otherwise, OID has never been in a set, and t is a default value (&A*". Clients are responsible for pin#in# servers often enou#h to ensure that they do not e(pire #iven the possibility of networ/ delays, lost pac/ets, and so on. If a client only re5uires access to a #iven object for what it would consider less than a time-out period for the object (that is, it receives and release the object in that period of time", then unless it is certain it has not itself passed the object to another client it must be sure to nevertheless pin# the object (a Co p(exP+n, that both adds and removes the OI* will suffice". &his ensures that an object will not e(pire as it is passed throu#h a chain of calls from one client to another. $n OID is said to be pin#ed when a set into which it was previously added and presently still resides is pin#ed with either a S+ p(eP+n, or a Co p(exP+n,, or when it is newly added to a set with Co p(exP+n,. 4ote that these rules imply that a Co p(exP+n, that removes an OID from a set still counts as a pin# on that OID. In addition to pin#in# the set SETID, this call sets the time-out period of the set as the product of a newlyspecified pin# period and a newly-specified pin# count to e(piration.! these values ta/e effect immediately. ,in# periods are specified in tenths of a second, yieldin# a ma(imum allowable pin# period of about 1 hr 3? min. $djustment of the time-out period of the set is considered to happen before the addition of any new OIDs to the set, which is in turn considered to happen before the removal of any OIDs from the set. &hus, an OID that is added and removed in a sin#le call no lon#er resides in the set, but is considered to have been pin#ed, and will have as its time-out at least the time-out period specified in that Co p(exP+n, call. On e(it, the server may re5uest that the client adjust the time-out period. that is, as/ it to specify a different time-out period in subse5uent calls to Co p(exP+n,. &his capability can be used to reduce traffic in busy servers or over slow lin/s. &he server indicates its desire throu#h the values it returns throu#h the variables pReISetP+n,Per+o' and pReISet4u P+n,sToT+ eOut. If the server see/s no chan#e, it simply returns the correspondin# values passed by the client. if it wishes a lon#er time-out period, it indicates lar#er values for one or both of these variables. if it wishes a smaller period, it indicates smaller values. +hen indicatin# a lar#er value, the server must start immediately actin# on that lar#er value by adjustin# the time-out period of the set. However, when indicatin# a smaller value, it must consider its re5uest as purely advice to the client, and not ta/e any action% if the client wishes to obli#e, it will do so in a subse5uent call to Co p(exP+n, by specifyin# an appropriate time-out period.
1>
&hat is, adjustin# the setDs time-out period after the OID has been removed from it has no effect on the time-out of the OID. Page '' DRAFT
*r "ment
/Rpc pSetI' SeIuence4u
Type
/an'(e2t SETID USHORT
De!cription $n ',C bindin# handle used to ma/e the re5uest. &he SETID bein# manipulated. &he se5uence number allows the object e(porter to detect duplicate pac/ets. 7ince the call is +'e potent, it is possible for duplicates to #et e(ecuted and for calls to arrive out of order when one pin# is delayed. Thi! parameter i! oin away5 Thi! parameter i! oin away. Thi! parameter i! chan in . &he server uses pReISetP+n,Per+o' to re5uest a new pin# period. If the re5uested period is shorter then the current period, the server must continue to use the current period until the client calls bac/. +hen the client calls bac/ the old re5uested period will only be used if the client specifies it as the new SetP+n,Per+o'. If the re5uested period is lon#er then the current period, the server must immediately be#in usin# the new period. However, if the client doesnDt accept it, the ne(t call will contain the old, shorter period. Thi! parameter i! chan in . &he server uses pReISet4u P+n,sToT+ eout to re5uest a new number of pin#s. If the number of pin#s is less then the current number of pin#s, the server must continue to use the current number of pin#s until the client calls bac/. +hen the client calls bac/ the old re5uested period will only be used if the client specifies it as the new Set4u P+n,sToT+ eout. If the re5uested number of pin#s is lar#er then the current number of pin#s, the server must immediately bein# usin# the new number of pin#s. However, if the client doesnDt accept it, the ne(t call will contain the old, smaller number of pin#s. &he si=e of the array A''ToSet. &he si=e of the array De(&ro Set. &he list of OIDs which are to be added to this set. $ddin# an OID to a set in which it already e(ists is permitted. such an action, as would be e(pected, is considered to pin# the OID. &he list of OIDs which are to be removed from this set. 'emoval counts as a pin#. $n IPID removed from a set will e(pire after the number of pin# periods has e(pired without any pin#s (not the number of pin# periods - 1". If an id is added and removed from a set in the same Co p(exP+n,, the id is considered to have been deleted.
SetP+n,Per+o' Set4u P+n,sToT+ eOut pReISetP+n,Per+o'
USHORT USHORT USHORT9
pReISet4u P+n,sToT+ eOut
USHORT9
cA''ToSet cDe(&ro Set A''ToSet
USHORT USHORT OID-.
De(&ro Set
OID-.
Return Value S2OE RPC2E2I43A6ID2O$%ECT RPC2E2ACCESS2DE4IED RPC2E2OUT2O&2ORDER E2OUTO&#E#OR7 E2U4EXPECTED Secur+ty re(ate' errors
Meanin 7uccess. &he set was pin#ed, etc. Indicates that some OID was not reco#ni=ed. &here is no recovery action for this error, it is informational only. 'eturned when a call is received with a se5uence number which is less then the last se5uence number e(ecuted successfully. &here was not enou#h memory to service the call. &he caller may retry addin# OIDs to the set on the ne(t pin#. $n unspecified error occurred. It is not /nown whether the pin# or any of the other actions were done or not. &A*
DRAFT
Page ',
)ervice Control Mana er

&he 7ervice Control Mana#er (7CM" is the component of the COM )ibrary responsible for locatin# class implementations and runnin# them. &he 7CM ensures that when a client re5uest is made, the appropriate server is connected and ready to receive the re5uest. &he 7CM /eeps a database of class information based on the system re#istry that the client caches locally throu#h the COM library. Machines in a COM environment which support the ability to instantiate objects on behalf of a remote client offer 7CM services remotely via an O',C interface. 13 &o ensure connectivity, such 7CM services reside at the same well-/nown endpoints as the COM Object 6(porter 1@ on each machine. 4ote that unli/e
C(+ent App(+cat+on
(1) Client: Create an Object
COM
( ) COM: !in" a Server
#n$Proce%% Object
RPC Connection to Local Server (&) COM: 'ere(% your )ointer

Local Object Proxy
SCM:
6ocates1 runs ser@ers1 J>K LHereMs your Connect+onN
Launc, a))lication
Local Object
Remote Object Proxy
*%+ remote SCM to launc, a))lication
RPC Connection to Remote Server
Remote Object
'i "re 4:74: COM dele ate! re!pon!ibility o/ loadin and la"nchin !erver! to the )CM5 the Object 6(porter service, which is re5uired for a machine to e(pose COM objects remotely, the e(posed 7CM service is in fact optional and some machines may not offer it. Clients may receive references to e(istin# objects on such a machine or cause objects to be instantiated on that machine throu#h means besides the services offered by the 7CM, such as a throu#h a moni/er bindin# mechanism. &hese capabilities are the basis for COMDs implementation locator services as outlined in -i#ure 13-1. +hen a client ma/es a re5uest to create an object of a C6SID, the COM )ibrary contacts the local 7CM (the one on the same machine" and re5uests that the appropriate server be located or launched, and a class factory returned to the COM )ibrary. $fter that, the COM )ibrary, or the client, can as/ the class factory to create an object. &he actions ta/en by the local 7CM depend on the type of object server that is re#istered for the C6SID% .n7Proce!! &he 7CM returns the file path of the *)) containin# the object server implementation. &he COM library then loads the *)) and as/s it for its class factory interface pointer. Local %emote &he 7CM starts the local e(ecutable which re#isters a class factory on startup. &hat pointer is then available to COM. &he local 7CM contacts the 7CM runnin# on the appropriate remote machine and forwards the re5uest to the remote 7CM. &he remote 7CM launches the server which re#isters a class factory li/e the local server with COM on that remote machine. &he remote 7CM then maintains a connection to that class factory and returns an ',C connection to the local 7CM which corresponds to that remote class
13 1@
4ot surprisin#ly, to #et around the chic/en and e## problem, #ettin# to a remote machineDs 7CM interface is not done via normal CoCreateInstance means. 'icher mechanisms for creatin# an interface to a remote 7CM are &A*, but note that the clarity about the 7CM-to-7CM interface and its endpoints ensure interconnectivity. &his is true despite final word whether the Object 6(porter will reuse the *C6 ',C 6ndpoint MapperDs endpoints or a different well-/nown set &A*, as noted above. Page 'DRAFT
factory. &he local 7CM then returns that connection to COM which creates a class factory pro(y which will internally forward re5uests to the remote 7CM via the ',C connection and thus on to the remote server. 4ote that if the remote 7CM determines that the remote server is actually an in-process server, it launches a surro#ate! server that then loads that in-process server. &he surro#ate does nothin# more than pass all re5uests on throu#h to the loaded *)). ISC#SC# interface is defined as follows (7CM7CM.I*)"%
55P------------------------------------------------------------------------55 55 -icro%oft Kindo2% 55 9op'ri86t (9) -icro%oft 9orporation, 1992 - 19953 55 55 CileL %c0%c03idl 55 55 /'nop%i%L ,nterface for /9- to /9- co00unication3 55 55 &6i% i% t6e interface t6at need% to be %upported b' 6o%t% t6at allo2 55 actiGation of ob"ect%3 !nl' one in%tance of t6i% interface can be e7ported 55 b' t6e 6o%t3 55 55-------------------------------------------------------------------------[ uuid(00000137-0000-0000-9000-000000000046), Ger%ion(130), pointer_default(unique) interface ,/9-to/9( B#:/F=& <ctiGation#eque%t( [in 6andle_t [in !#.9&B,/ O [out !#.9&B<& O [in con%t DF,* O [in, %trin8, unique K9B<# O [in *K!#* [in *K!#* [in *K!#* [in,unique,%iMe_i%(,nterface%) ,,* O [out,%iMe_i%(,nterface%) !$>#:C OO [out,%iMe_i%(,nterface%) B#:/F=& O )4 H
6#pc, orpct6i%, orpct6at, rcl%id, p2%M!b"ect+a0e, cl%ct7, 8rf-ode, d29ount, p,,*%, pp,nterface%, p#e%ult%
.)CMto)CM::*ctivation%e9"e!t H'67:)& I7CMto7CM%%$ctivation'e5uest(h'pc, orpcthis, orpcthat, rclsid, pws=Object4ame, clsct(, #rfMode, dwCount, pII*s, ppInterfaces, p'esults". &his sin#le method encapsulates several different forms of activatin# and instantiatin# objects on the machine of this 7CM. +hen pIIDs is 4U66, this function behaves rou#hly as Co*etC(assObjectJrc(s+'1 c(sctx1 4U661 IID2IC(ass&actory1OK, returnin# a class-object to the caller. +hen p"s8Object4a e and pObjectStora,e are 4U66, this function behaves rou#hly as CoCreateInstanceExJrc(s+'1 4U661 c(sctx1 OK. Otherwise, this function acts rou#hly similar to Create&+(e#on+!erJp"s8Object4a e1 OK followed by I#on+!er))$+n'ToObjectJOK to retrieve the re5uired interfaces.
DRAFT
Page '5
*r "ment
/Rpc orpct/+s orpct/at rc(s+' p"s8Object4a e
Type
/an'(e2t
De!cription
c(sctx ,rf#o'e '"Count pIIDs ppInterfaces pResu(ts Return Value S2OE CO2S24OTA66I4TER&ACES
$n ',C bindin# handle used to ma/e the re5uest. ORPCTHIS identifyin# this object. ORPCTHAT9 ORPCTHAT holdin# return values. C6SID9 Identifies the class to be run to service the re5uest. PCHAR9 Identifies the persistent representation of the object to this machine. &ypically, this is a file name which is used to determine the class, as in Create&+(e#on+!erJp"s8&+(e4a e1 Qp !K followed by $+n'#on+!erJp !OK. DPORD Malues ta/en from the C6SCTX enumeration. DPORD Malues ta/en from the ST*# enumeration. DPORD &he number of interfaces to return. IID9 $n array of interfaces to QueryInterface for on the new object. O$%RE&99 )ocation to return an array of interfaces on the object. HRESU6T9)ocation to return an array of return codes about the successful retrieval of each of the '"Count interfaces.
ORPCTHIS9
Meanin 7uccess. 7ome but not all of the '"Count interfaces were returned in ppInterface*ata. 6(amine pResu(ts to identify e(actly which interf
6rappin
DC& %PC call! to interoperate with O%PC
&his is an e(ample of a server side wrapper for the Aar method. It assumes the e(istence of small helper functions to import and e(port object references and loo/up previously e(ported object references.
RPC2STATUS $arJ/an'(e2t /1 s/ort +1 O$%RE& 9 prI$1 O$%RE& 99 pprIPK A UUID +p+'R RPC2STATUS statusR I&oo 9 pI&R I$ar 9 pI$R IPa8 9 PIPR HRESU6T /RR status S Rpc$+n'+n,InIObjectJ/1 Q+p+'KR +f JstatusK returnJSO#ETHI4*KR status S ORpc6oo!upIPIDJ+p+'1 QpI&KR +f JstatusK returnJSO#ETHI4*KR status S ORpcI portObjRefJprI$1 QpI$KR +f JstatusK returnJSO#ETHI4*KR /R S pI&0F$arJ+1 pI$1 QpIPKR HH actua( ca(( to t/e et/o'T
pI$0FRe(easeJKR status S ORpcExportObjRefJpIP1 pprIPKR returnJ/R U /R ) SO#ETHI4*KR DR
&his is an e(ample of the client side wrapper for Aar%

HH assu e so e c(ass C&oo t/at + p(e ents $ar et/o' c(ass C&oo ) IUn!no"n1 I&oo A UUID +p+'R HH one for eac/ +nterfaceU /an'(e2t /R @+rtua( HRESU6T QueryInterfaceJUUID ++'1 @o+' 99pp@o+'KR @+rtua( HRESU6T A''RefJKR @+rtua( HRESU6T Re(easeJKR @+rtua( HRESU6T $arJs/ort +1 I&oo 9 pI&1 IPa8 99 ppIPKR DR HRESU6T C&oo))$arJs/ort +1 I&oo 9 pI&1 IPa8 99 ppIPK A O$%RE& 9 prI&R O$%RE& 9 prIPR
Page '.
DRAFT
HRESU6T /RR RPC2STATUS statusR status S Rpc$+n'+n,SetObjectJt/+s0F/1 t/+s0F+p+'KR +f JstatusK returnJSO#ETHI4*KR status S ORpcExportObjRefJpI&1 QprI&KR +f JstatusK returnJSO#ETHI4*KR /R S $arJt/+s0F/1 +1 prI&1 QprIPKR status S ORpcI portObjRefJprIP1 ppIPKR ORpc&reeObjRefJprI&KR ORpc&reeObjRefJprIPKR DR returnJ/R U /R ) SO#ETHI4*KR
.mplementin O%PC in %PC

Since the implicit parameters are specified as IDL, the ORPC header received by RPC will contain many fields inserted by MIDL. Here are the definitions for the header on the wire.
H9 An +nboun' /ea'er "ou(' be (a+' out as fo((o"s "/ere t/e extent array +s opt+ona( an' t/ere ay be 8ero of ore extents. An outboun' /ea'er +s (a+' out s+ +(ar(y. ORPCTHIS2PITH4OEXTE4SIO4S ORPC2EXTE4T2ARRA7 -ORPC2EXTE4T.9 . 9H type'ef struct A CO#3ERSIO4 @ers+onR HH CO# @ers+on nu ber uns+,ne' (on, f(a,sR HH I4&O f(a,s for presence of ot/er 'ata uns+,ne' (on, reser@e':R HH set to 8ero 6TID (t+'R HH (o,+ca( t/rea' +' of ca((er uns+,ne' (on, un+IueR HH ta, to +n'+cate presence of extens+ons D ORPCTHIS2PITH4OEXTE4SIO4R type'ef struct A uns+,ne' (on, roun'e'2s+8eR HH Actua( nu ber of extents. uu+'2t +'R HH Extens+on +'ent+f+er. uns+,ne' (on, s+8eR HH Extens+on s+8e. byte 'ata-.R HH Extens+on 'ata. D ORPC2EXTE4TR HH Array of extens+ons. type'ef struct A uns+,ne' (on, roun'e'2s+8eR HH Actua( nu ber of extents uns+,ne' (on, s+8eR HH 4u ber of extents uns+,ne' (on, un+Iue2f(a,-.R HH &(a,s to +n'+cate presense of ORPC2EXTE4Ts D ORPC2EXTE4T2ARRA7R type'ef struct A uns+,ne' (on, f(a,sR HH I4&O f(a,s for presence of ot/er 'ata uns+,ne' (on, un+IueR HH ta, to +n'+cate presence of extens+ons D ORPCTHAT2PITH24OEXTE4SIO4SR
&his pa#e intentionally left blan/.
DRAFT
Page '/

CH15 Network Protocol

Transféré par

Informations du document

Titre original

Copyright

Formats disponibles

Partager ce document

Partager ou intégrer le document

Options de partage

Avez-vous trouvé ce document utile ?

Ce contenu est-il inapproprié ?

Droits d'auteur :

Formats disponibles

CH15 Network Protocol

Transféré par

Droits d'auteur :

Formats disponibles

The COM Specification

Chapter 15. COM Network Protocol

0Part V: The COM Library

Cop!right " 1##5 Micro$oft Corporation All Right$ Re$er%e&

Chapter 15. COM Network Protocol

The COM Specification

Component Object Model Network Protocol

Cop!right " 1##5 Micro$oft Corporation All Right$ Re$er%e&

The COM Specification

Chapter 15. COM Network Protocol

OXIDs, Object Exporters, & Machines

Marshaled Interface References

Chapter 15. COM Network Protocol

The COM Specification

Cop!right " 1##5 Micro$oft Corporation All Right$ Re$er%e&

The COM Specification

Chapter 15. COM Network Protocol

Cop!right " 1##5 Micro$oft Corporation All Right$ Re$er%e&

Chapter 15. COM Network Protocol

The COM Specification

Data type! and !tr"ct"re!

DCE Pac"et #eaders

are all allowed in ORPC. Interface pointers may not be passed on

Object RPC $ase Definitions

Cop!right " 1##5 Micro$oft Corporation All Right$ Re$er%e&

The COM Specification

Chapter 15. COM Network Protocol

55 fla8 Galue% for !$>#:C

Cop!right " 1##5 Micro$oft Corporation All Right$ Re$er%e&

Chapter 15. COM Network Protocol

The COM Specification

con%t con%t con%t con%t con%t

un%i8ned un%i8ned un%i8ned un%i8ned un%i8ned

lon8 lon8 lon8 lon8 lon8

!$>#:C_/&<+*<#* ? !$>#:C_B<+*=:# ? !$>#:C_=!+D/&* ? !$>#:C_=!+DB*=# ? !$>#:C_9F/&!- ? 164

Cop!right " 1##5 Micro$oft Corporation All Right$ Re$er%e&

The COM Specification

Chapter 15. COM Network Protocol

con%t con%t con%t con%t con%t con%t

un%i8ned un%i8ned un%i8ned un%i8ned un%i8ned un%i8ned

lon8 lon8 lon8 lon8 lon8 lon8

,+C!_+F== ,+C!_=!9<= ,+C!_#:/:#;:*1 ,+C!_#:/:#;:*2 ,+C!_#:/:#;:*3 ,+C!_#:/:#;:*4

Cop!right " 1##5 Micro$oft Corporation All Right$ Re$er%e&

Chapter 15. COM Network Protocol

The COM Specification

Cop!right " 1##5 Micro$oft Corporation All Right$ Re$er%e&

The COM Specification

Chapter 15. COM Network Protocol

Crefs Ip+' O+' Ox+'

SOR&2OXRES: SOR&2OXRES< SOR&2OXRES> SOR&2OXRES?

f(a,s reser@e' c+' extens+ons

uns+,ne' (on, uns+,ne' (on, CID ORPC2EXTE4T2ARRA79

&he various ORPCI4&O&6A*S have the followin# meanin#s.

Chapter 15. COM Network Protocol

The COM Specification

Debug Infor*ation $od! Extension

Extended Error Info $od! Extension

Cop!right " 1##5 Micro$oft Corporation All Right$ Re$er%e&

The COM Specification

Chapter 15. COM Network Protocol

Cop!right " 1##5 Micro$oft Corporation All Right$ Re$er%e&

Chapter 15. COM Network Protocol

The COM Specification

!$>#:C_/&<+<# ? !$>#:C_B<+=:# ? !$>#:C_=!+D/& ? !$>#:C_=!+DB*=# ? !$>#:C_9F/&!- ? 164

,+C!_+F== ,+C!_=!9<= ,+C!_#:/:#;:1 ,+C!_#:/:#;:2 ,+C!_#:/:#;:3 ,+C!_#:/:#;:4

.%em-nknown::%emdd%e/ H'67:)& I'em:n/nown%%'em$dd'ef(cInterface'efs, r#'efs" r "ment Type De!cription