CH15 Network Protocol.doc

8/14/2019 CH15 Network Protocol.doc

1/27

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, someimplementation 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 aspecification 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 echan#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" thatincludes%

$ 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 thefacilities to epose 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 ofindirection, usually a system re#istry, between the identity of an object class and the pac/a#in# ofthe implementation such that clients are independent of the pac/a#in# which can chan#e in thefuture.

&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 eample, Microsoft has implemented COM on Microsoft +indows 0.1, Microsoft +indows23, Microsoft +indows 4&, and the $pple Macintosh.

&he followin# chapter describes elements of the COM )ibrary that a vendor implementin# COM on apreviously unsupported platform would re5uire.

DRAFT Page 1 Cop!right " 1##5 Micro$oft CorporationAll Right$ Re$er%e&


2/27

Chapter 15. COM Network Protocol The COM Specification

Component Object Model Network Protocol

&he COM networ/ protocol is a protocol for object-oriented remote procedure calls and is thus also calledObject 'C or O'C. &he Object 'C protocol consists of a set of etensions, layered on the distributedcomputin# 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 theimplementation effort involved in implementin# the COM networ/ protocol is in fact that ofimplementin# 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;is of course set to encompass the entire body of the ault *:, includin# theORPCTHAT. In the Connection-oriented (CO" ault *:, the ORPCTHATis placed in the standard location

1 $s in *C6 'C object I*s are indeed only ever interpreted relative to a #iven machine, this relain# of the *C6 specificationis not problematic.

; &he II* in the interface I* field is from a lo#ical perspective actually redundant because the II* uni5uely specifies an interface pointer(thou#h the II* is not recoverable from just the II*". However, an additional (optional" chec/ to verify that the caller and callee a#reeon the type of the interface pointer would ma/e the system more robust. $lso, the specification of the actual II* in 5uestion eases theinte#ration of the COM networ/ protocol with the *C6 'C networ/ protocol. 4ote that it is not epensive for callers to provide theII* since the space for the II* is allocated in the *C6 'C header, which is always transmitted anyway.

0 or the specification of the Connectionless ault *:, see 8C$6 'C9, pa#e 3;?. a#e 303 of the same wor/ describes theConnection-oriented ault *:.

> Ibid, pa#e 31@.

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

Thi$ page intentionall! left (lank.


3/27


allocated for the stub data.!3In a ault *: of either form that results from an O'C, if an ORPCTHAT isnot present then no other data may be substituted in its here-specified location in the *:.

OXIDs, Object Exporters, & Machines

$lthou#h an IPID from a lo#ical perspective semantically determines the server, object and interface towhich 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 eporteridentifier, otherwise /nown as an OXID. Conceptually, an OXID can be thou#ht of as an implementationscope 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 eact definition of such scopes has no bearin# on theCOM 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. *atastructures in each Object 6porter /eep trac/ of the IPIDs eported and imported by that Object 6porter.&he Object 6porter resides at well-/nown endpoints (one per protocol, of course" on the machine. Itsupports 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. Aeforema/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 thedestination 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 wasac5uired, which is not necessarily the home machine for the interface pointer" for the translation, andsaves 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 6porter" is COM object termed an OXID object.! OXIDobjects implement (at least" the IReUn!no"n interface, throu#h which remote mana#ement of referencecounts and re5uests for interfaces are returned.

6ach machine is represented by a #ID. #IDs are UUIDs and thus universally uni5ue. &he #ID for amachine may (should" chan#e when the machine reboots. However, when the #IDfor a machine chan#es,all OBI*s, OIDs, and IPIDson that machine become invalid. #IDsare an optimi=ation to simplify the tas/of determinin# which OXIDsare eported and pin#ed by which object eporters.

Marshaled Interface References

&he COM networ/ protocol etends the 4etwor/ *ata 'epresentation standard specified in 8C$6 'C9by definin# what can be thou#ht of as a new primitive data type that can be marshaled% that of an interfacereference to a COM object.@&his is the only etension 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 detailbelow. $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 IPID is

found. OIDs are UUIDs they are universally uni5ue.

$n OXID, which identifies the scope where the implementation of the object is active, and canbe used to reach the interface pointer.

3 &hat is, in the Connection-oriented case, the ORPCTHAT also follows four bytes of paddin# after the fault code however, thefault 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 eistin# data types dependson 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 referencewithout /nowin# the II*. &he II* does uni5uely specify an II* however, you canDt al#orithmically derive the II* from the II*.&his is not a problem because the II* does not have to be eplicitly specified it is either implicitly specified (by the type of thear#ument in a MI*) declaration" or available eplicitly as another ar#ument in the call that is carryin# the polymorphic objectreference (for eample, I:n/nown%%EueryInterface".

DRAFT Page , Cop!right " 1##5 Micro$oft CorporationAll Right$ Re$er%e&


4/27


$ 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 net section".

7ome fla#s, eplained 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 class-

specific 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 proxyobject that caches state. In this case, the class-specific information is just a standardreference 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 orderprevailin# 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 aslocal reference countin# is carried out on a per interface basis.

&he actual increment and decrement calls are carried out usin# (respectively" the ReA''Ref andReRe(ease methods in a COM interface /nown as IReUn!no"nfound on an object associated with theeach OXID, the IPID of which is returned from the function IObjectExporter))*etStr+n,$+n'+n,s(see below".Incontrast to their analo#ues in IUn!no"n, ReA''Ref and ReRe(easecan in one call increment or decrementthe 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 eachlocalA''Ref and Re(ease into a remote ReA''Ref and ReRe(ease. 'ather, the actual remote release of allinterfaces 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 referencecounts 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.#:C_=!+DB*=# ? @ lon8 for andler ob"ref con%t un%i8ned lon8 !$>#:C_F/&! ? 16 cu%to ar%alled ob"ref

fla8 Galue% for a /&*!$>#:C /ould be an enu but *: *= doe% not %upport %par%e enuerator% !A#:/1 - !A#:/4 are re%erGed for te ob"ect eporter% u%e onl', ob"ect iporter% %ould i8nore te and not enforce $N con%t un%i8ned lon8 /!#C_+!.+D ? 1 .in8in8 i% not required con%t un%i8ned lon8 /!#C_!A#:/1 ? @ re%erGed for eporter con%t un%i8ned lon8 /!#C_!A#:/2 ? 16 re%erGed for eporter con%t un%i8ned lon8 /!#C_!A#:/3 ? 32 re%erGed for eporter con%t un%i8ned lon8 /!#C_!A#:/4 ? 64 re%erGed for eporter

#e%erGed fla8 Galue% for a /&*!$>#:C con%t un%i8ned lon8 /!#C_C#::&B#:#:C

un%i8ned lon8 fla8% /&*!$>#:C fla8%un%i8ned lon8 c#ef% count of reference% pa%%ed.* ipid ipid of nterface!* oid oid of ob"ect it ti% ipid

!A* oid oid of %erGer it ti% oid H /&*!$>#:C

forat of a ar%alled interface pointer t'pedef %truct ta8!$>#:C

un%i8ned lon8 fla8% !$>#:C fla8% (%ee aboGe)

[%itc_i%(fla8%), %itc_t'pe(un%i8ned lon8) union [ca%e(!$>#:C_/&


9/27


con%t un%i8ned lon8 +C!_+F== ? 0 no additional info in pacJet con%t un%i8ned lon8 +C!_=!


10/27


O#$%&'()T*ND*%D

Contains one interface of an object marshaled in standard form. &he data that follows the switch fla# is aSTDO$%RE&structure (described below".

O#$%&'(+*NDL&%

$ marshalin# of an object that wishes to use handler marshalin#. or eample, an object wishes to berepresented in client address spaces by a proy object that caches state. In this case, the class-specificinformation is just a standard reference to an interface pointer that the handler (proy object" will use tocommunicate with the ori#inal object. 7ee the ISt'#ars/a(Info interface.

Member Type )emanticst' STDO$%RE& $ standard object reference used to connect to the source object.C(s+' C6SID &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 ofprotocol se5uences and networ/ addresses that can be used to bind to an OXIDresolver that is able toresolve the OXIDin the STDO$%RE&. &his is useful when marshalin# a proy to #ive to another machine(a./.a. the middleman! case". &he marshalin# machine can specify the saResA''rfor the resolver on theserver 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 OXIDin its cache beyond the lifetime of itsown references in order to satisfy re5uests from parties that it just #ave the O$%RE&to.

Member Type )emanticst' STDO$%RE& $ standard object reference used to connect to the source object.SaResA''r STRI4*ARRA7 &he resolver address.

O#$%&'(LON,+DL%

Contains the same information as the handler case as well as the object resolver address. &his form isneeded for the same reason O$%RE&26O4*STD is needed.

Member Type )emanticst' STDO$%RE& $ standard object reference used to connect to the source object.C(s+' C6SID &he class I* of the handler.SaResA''r STRI4*ARRA7 &he resolver address.

O#$%&'(C-)TOM

$ marshalin# of an object which supports custom marshalin#. &he Custom format #ives an object controlover the representation of references to itself. or eample, 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 Type )emanticc(s+' C6SID &he C6SID of the object to create in the destination client.s+8e uns+,ne' (on, &he si=e of the marshaled data provided by the source object and passed here in

pData.pData byte9 &he data bytes that should be passed to I#ars/a())Unars/a(Interfaceon 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# thestandard COM networ/ protocol. $ STDO$%RE& in #eneral can only be interpreted in the contet of anoutstandin# O'C, for it may contain an OXID un/nown to the machine on which it is unmarshaled, and itis 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 )emanticf(a,s la# values ta/en from the enumeration SOR&&6A*S. &hese are described below.

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


11/27


Crefs &he number of reference counts on +p+' that bein# transferred in this marshalin#.Ip+' &he IPID of the interface bein# marshaled.O+' &he OID of the object to which +p+' corresponds.Ox+' &he OXID of the server that owns this OID.

&he various SOR&6A*S values have the followin# meanin#s. &he SOR&2OXRESxbit fla#s are reserved forthe object eporterDs use only, and must be i#nored by object importers. &hey need not be passed throu#hwhen marshalin# an interface proy.

'la Val"e MeaninSOR&24OPI4* : &his OIDdoes 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 objectand its interfaces are still permitted, however, thou#h such action is pointless.

SOR&2OXRES: ; 'eserved for eporter.SOR&2OXRES< := 'eserved for eporter.SOR&2OXRES> >< 'eserved for eporter.SOR&2OXRES? =? 'eserved for eporter.

ORPC(#I'

In every 'e5uest *: that is an O'C, the body (C) case" or the stub data (CO case" which normallycontains the marshaled ar#uments in fact be#ins with an instance of the ORPCTHIS structure. &hemarshaled 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 ifnecessary to achieve an overall si=e that is a multiple of ei#ht bytes thus, the remainin# ar#uments are asa whole ei#ht byte ali#ned.

$s in re#ular calls, the causality id must be propa#ated. If $ calls CoputeP+on A, A calls Re(easeon C(which #ets converted to ReRe(ease", and C calls A''on $, $ will see the same causality id that it calledA with.

Member Type )emantic@ers+on CO#3ERSIO4 &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 senderDsmajor and minor O'C version numbers. &he clientDs and serverDs majorversions must be e5ual. Aac/ward compatible chan#es in the protocol areindicated by hi#her minor version numbers. &herefore, a serverDs minorversion must be #reater than or e5ual to the clientDs. However, if theserverDs minor version eceeds the clientDs minor version, it must return

the clientDs minor version and restrict its use of the protocol to the minorversion specified by the client. $ protocol version mismatch causes theRPC2E23ERSIO42#IS#ATCH ORPCfault to be returned.

f(a,s uns+,ne' (on, la# values ta/en from the enumeration ORPCI4&O&6A*S. &hese areelaborated below.

reser@e' uns+,ne' (on, Must be set to =ero.c+' CID &he causality id of this O'C. 7ee comments below.extens+ons ORPC2EXTE4T2ARRA79 &he body etensions, if any, passed with this call. Aody etensions are

*UID-ta##ed blobs of data which are marshaled as an array of bytes.6tensions are always marshaled with initial ei#ht byte ali#nment. Aodyetensions which are presently defined are described below.

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

'la MeaninI4&O24U66 (4ot a real fla#. Merely a defined constant indicatin# the absence of any fla# values."

I4&O26OCA6 &he destination of this call is on the same machine on which it ori#inates. &his value is neverto be specified in calls which are not in fact local.

I4&O2RESER3ED: If I4&O26OCA6 is set, then reserved for local use otherwise, reserved for future use.I4&O2RESER3ED< If I4&O26OCA6 is set, then reserved for local use otherwise, reserved for future use.I4&O2RESER3ED> If I4&O26OCA6 is set, then reserved for local use otherwise, reserved for future use.I4&O2RESER3ED? If I4&O26OCA6 is set, then reserved for local use otherwise, reserved for future use.

Implementations may use the local and reserved fla#s to indicate any etra information needed for localcalls. 4ote that if t/e I4&O26OCA6bit is not set and any of the other bits areset then the receiver shouldreturn a fault.

Comment!



12/27


&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 samecausality id. &his allows simple servers to avoid wor/in# on more then one thin# at a time (for eample$ 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# eceptions.

&he causality id for aybeand +'epotentcalls 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 etensions to the channel header. &wo are currently defined for MicrosoftDsimplementation of this protocol (described below". Other implementations may define their ownetensions with their own ::I*s. Implementations should s/ip over etensions they do not reco#ni=e orwish to support. 4ote that in order to force the ORPCTHISheader to be < byte ali#ned an even number ofetensions must be present and the si=e of the etension data must be a multiple of


13/27


&he second variation is suitable for use in remote situations where one or the other of the re5uirements ofthe use of the first variation cannot be upheld. &his second variation specifies the followin# members%

Member De!criptionuu+'ErrorSeant+c $ UUID si#nifyin# the semantic of the error.u(ErrorSeant+c $ four-byte 5uantity that 5ualifies the error semantic. &he semantics of these four bytes are

completely determined by the uu+'ErrorSeant+c.cbData &he si=e of the data passed in pbData.

pbData *ata associated with the error marshaled as an array of bytes. &he interpretation of these bytesis #overned by the uu+'ErrorSeant+c.

"s8ErrorStr+n, $n error strin# suitable for display to a human user. &his is in fact of somewhat little use, as theserver returnin# the error can usually only #uess as to the appropriate lan#ua#e in which to formthis strin#. However, the ability to pass such as strin# as a last resort is provided here.

(c+'ErrorStr+n, &he locale contet in which the error strin#, if any, is formed. )ocale constants are as in theMicrosoft +in0; $I.

&he third variation allows for etensibility of the error information bein# passed. It specifies an objectreference (an O$%RE&". In practice, this reference most always contains a custom marshaled object, thou#hthis is not re5uired.

.%em-nknown inter/ace

&he IReUn!no"n interface is used by remote clients for manipulatin# reference counts on the IPIDs thatthey hold and for obtainin# additional interfaces on the objects on which those IPIDs are found. &hisinterface is implemented by the COM OBI* object! associated with each OXID (nb. not each Object6porter". &he IPIDfor the IReUn!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 referencecounted.

IReUn!no"n is specified as follows (RE#U4.ID6"%

P------------------------------------------------------------------------- icro%oft Kindo% op'ri8t () icro%oft orporation, 1992 - 1995 CileL reunJidl &e reote Ger%ion of FnJnon !nce in%tance of ti% interface ei%t% per !A* (eter an !A* repre%ent% eiter a tread or a proce%% i% ipleentation %pecific) &i% interface i% pa%%ed alon8 durin8 !A* re%olution t i% u%ed b' client% to quer' for ne interface%, 8et additional reference% (for ar%allin8), and relea%e out%tandin8 reference%P-------------------------------------------------------------------------[ ob"ect, uuid(99fcff2@-5260-101b-bbcb-00aa0021347a)

iport unJnnidl

interface #eFnJnon L FnJnon

return %tructure fro a T call t'pedef %truct ta8#:T#:/F=&

B#:/F=& #e%ult re%ult of call/&*!$>#:C %td data for returned interface

H #:T#:/F=&

B#:/F=& #eTuer'nterface (

[in .* ipid, interface to T on[in un%i8ned lon8 c#ef%, count of


14/27


)

%tructure pa%%ed to


15/27


.%em-nknown::%em*dd%e/

H'67:)& I'em:n/nown%%'em$dd'ef(cInterface'efs, r#'efs"

*r"ment Type De!cription

cInterfaceRefs uns+,ne' s/ort &he si=e of the r,Refs array.

r,Refs RE#I4TER&ACERE& $n array of IPID1 cRefspairs, cInterfaceRefs (ar,e. 6ach IPID indicates an

interface mana#ed by thisOXID

on whom more reference counts aresou#ht. &he correspondin# reference count (cRefs", which may not be=ero (and thus is one or more", indicates the number of referencecounts sou#ht on that IPID.

Return Value MeaninS2O 7uccess. $n attempt was made to retrieve each of the re5uested interfaces.E2I43A6IDAR* One or more of the IPIDsindicated were not in fact mana#ed by this OBI*, or

one or more of the re5uested reference counts was =ero. None of there5uested reference countshave been #ranted to the caller the call is a no-op.

E2U4EXPECTED $n unspecified error occurred. It is un/nown whether any or all of there5uested reference counts have been #ranted.

Comment!

$ useful optimi=ation is for a caller to ReA''Ref more than needed. +hen a process receives an outmarshaled 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 alar#e number of references. &hen if the interface is passed out multiple times, no new remote calls areneeded to #ain additional references.

$ marshaler may optionally specify more than one reference in the STDO$%RE&when marshalin# aninterface. &his allows the middle man case to pre-fill its cache of references without ma/in# an etraReA''Refcall. &he number of references passed is always specified in the STDO$%RE&field.

.%em-nknown::%em%elea!e

H'67:)& I'em:n/nown%%'em'elease(cInterface'efs, r#'efs"


cInterfaceRefs USHORT &he si=e of the r,Refs array.

r,Refs RE#I4TER&ACERE& $n array of IPID, cRefspairs, cInterfaceRefslar#e. 6ach IPIDindicates aninterface mana#ed by this OXIDon 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 referencecounts returned on that IPID.

Return Value MeaninS2O 7uccess. $n attempt was made to retrieve each of the re5uested interfaces.E2I43A6IDAR* One or more of the IPIDsindicated were not in fact mana#ed by this OXID, or

one or more of the re5uested reference counts was =ero. Noneof the offeredreference counts have been accepted by the server the call is a no-op.

E2U4EXPECTED $n unspecified error occurred. It is un/nown whether any or all of the offeredreference counts have been accepted.

The Object &1porter

6ach machine that supports the COM networ/ protocol supports a one-per-machine service /nown as themachineDs LObject 6porter.D Communication with an Object 6porter is via a *C6 'C, not an O'C.&o ensure connectivity, the Object 6porter resides at well-/nown endpoints. It is proposed that the Object6porter 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.


Obtain and #rant ownership to the caller of one or more referencecountson one or more IPIDs mana#ed bythe correspondin# OXID.

'elease ownership of one or more reference countson one or more IPIDs mana#ed by the correspondin#OXID.


16/27


alternately and less preferably (;" that the Object 6porter reside at a different set of well-/nownendpoints &A*.

&he Object 6porter performs several services%

It caches and returns to clients when as/ed the strin# bindin#s necessary to connect to OXIDs of

eported objects for which this machine is it either itself a client or is the server. 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 6porter may be as/ed for the information re5uired to connect to one of two different /inds ofOXIDs, either the OXIDs associated with its own objects, or the OXIDs associated with objects for which ititself is a client, and which it has passed on to a second client machine. &his second case, where onemarshals an object from one client machine to a second, is collo5uially referred to the middleman ! case.In the middleman case, the eporter is re5uired to retain the connection information associated with theOXIDsthat it passes on until it is certain that that the second client machine no lon#er needs them. Moreon this below.

IObjectExporterinterface is defined as follows (OAG6B.I*)"%

P-------------------------------------------------------------------------

icro%oft Kindo% op'ri8t () icro%oft orporation, 1992 - 1995 CileL ob"eidl /'nop%i%L nterface ipleented b' ob"ect eporter% &i% i% te interface tat need% to be %upported b' o%t% tat eport ob"ect% !nl' one in%tance of ti% interface can be eported b' te o%t


17/27


[in andle_t #pc, [in !A* Op!id, [in un%i8ned %ort c#eque%ted.rot%eq%, [in, ref, %iMe_i%(c#eque%ted.rot%eq%) un%i8ned %ort ar#eque%ted.rot%eq%[, [out, ref * Opid, [out, ref /+D


18/27


of the server. If the list of re5uested protocol se5uences is a (perhaps non-proper" subset in order of aprotocol se5uence list previously re5uested of the server, then the correspondin# cached strin# bindin#smay be returned immediately to the caller without actually communicatin# with the server. Otherwise, theactual psaReueste'Protsesmust 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 usein later calls.

In order to support the middleman case, Object 6porters 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 tbe the full time-out period (pin# period number

of pin#s to time-out" for some OID (any OID" for which this Object 6porters is a client and which residesin OXID. &hen the Object 6porter must /eep the bindin# information for OXID for at least an amount oftime 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 learnwhich OXIDs are collocated on the same machine, and thus which OIDs may be appropriately #roupedto#ether in pin# sets (see Cop(exP+n,". &he machine identifier is #uaranteed not to chan#e so lon# as thereare remote references to objects on the machine which remain valid. &hus, specifically, the machine idmay chan#e as the machine reboots.

Reso(@eOx+' also informs the caller of the IPID of the OXID object associated with this OXID.


/Rpc /an'(e2t $n 'C bindin# handle used to ma/e the re5uest.pOx+' OXID9 &he OXID for whom strin# bindin#s are re5uested. . &he OBI*

may or may not represent a process on the machine that receivesthe Reso(@eOx+'call

cReueste'Protses uns+,ne' s/ort &he number of protocol se5uences re5uested.

arReueste'Protses uns+,ne' s/ort- arReueste'Protsesmust be initiali=ed with all the protocol idDsthe client is willin# to use to reach the server. It cannot containlocal protocol se5uences. &he object eporter must ta/e care oflocal 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.

p+' #ID9 &he machine identifier associated with OXID.

psaOx+'$+n'+n,s STRI4*ARRA799&he strin# bindin#s supported by this

OXID, in preferential order.4ote that these are :nicode strin#s.

p+p+'ReUn!no"n IPID9 &he IPID to the IReUn!no"n interface the OXID object for thisOXID.

Return Value MeaninS2O 7uccess. &he re5uested information was returned.RPC2E2I43A6ID2O$%ECT

RPC2E2I43A6ID2OXID &his OXID is un/nown to this Object 6porter, and thus no information wasreturned.

RPC2E2SER3ER2DIED

E2OUTOE#OR7

E2U4EXPECTED $n unspecified error occurred. 7ome of the re5uested information may not bereturned.

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 storingpersistent 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, IPIDsand OIDs.

Conversely, since object references are aged, it is the responsibility of each client to unmarshal them andbegin pinging them in a timely fashion.

10 &his time-out period does notguaranteethat OBI* information will not be discarded before clients may need it, but is a very #oodheuristic, and indeed better than a hard-coded time-out value.

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


19/27


The basic use of the Reso(@eOx+'method is to translate an OXIDto string bindings. Put another way, thismethod translates an opaque process and machine identifier to the information needed to reach thatmachine and process. There are four interesting cases: looking up an OXIDthe first time an interface is

unmarshaled on a machine, looking up an OXIDbetween a pair of machines that already have connections,looking up an OXIDfrom a middleman, and looking up string bindings with unresolved endpoints (lazy useprotseq). 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 resolveOXID G

ask OX E to resolveOXID G

look up G

and returnGs

endpoints.Construct and cachestring binding vectorfor 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 eporter C already /nows the strin# bindin#s for object eporter 6 and process , but not processN. Object eporter 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 OXIDforN before, it as/s its local object eporter to resolve N. rocess * also has to tell object eporter C where it

#ot the reference from, in this case, process . Object eporter C does not reco#ni=e the OBI* N.However it does reco#ni=e the OXID and /nows the object eporter 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 Cwith the machine id A. OB C caches this information so that if * ever #ets a reference from N, it /nowswho to as/ to resolve that reference.

My 'ir!t Look"p

&he previous eample assumes that OB C already /nows about OB 6 and process * is already tal/in# toprocess . 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. &husdifferent vendors may have different activation models. However there is one basic form of activationshared by all O'C. If two processes can communicate via *C6 'C, they can pass lon# standard objectreferences. +hile this is not epected to be a common form of activation, it is a simple one that shouldcertainly 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 andOXIDfor

call with raw 'C

pass an out ref to

pass IIDas additionalparameter

tell C the OXID2I4&O and

DRAFT Page 1# Cop!right " 1##5 Micro$oft CorporationAll Right$ Re$er%e&


20/27


#ID for . Includenetwor/ address(es".

compute thestrin# bindin#sfor OB 6 from

as/ 6 to resolve

to #et machineid and endpointsfor

return endpoints andmachine id

ready to call via O'C

&his eample points out that there has to be a local interface between processes and the local objecteporter.

Middleman Look"p

&he net case shows how loo/up wor/s between multiple machines. 7uppose that 6 has a reference to Nand N has a reference to I. 7imilarly, * /nows about and N and /nows about H and I. +hat happensif N passes a reference to I over to 6

OX D Process E OX F Process G OX H Process Icall G

return a longreference to I

ask D tolookup I

Since its a long ref to I

call Reso(@eOx+'on H.

Returnendpoints

to I

Compute string bindings

to I from endpoints andnetwork addresses.

return string bindings toE

ready tocall I

4ote that when process N returned a reference to I, it used he lon# form of the O$%RE&which includes theprotocol idDs and networ/ addresses of the OXIDresolver for process I (in this eample, the addresses forOB H". &his would results in OB * callin# OB H directly, rather than needin# to call OB . &headvanta#e of this is that if no references to process I needed by OB , it could remove it from its OXIDcache at any time, rather than /eepin# it around at least until OB * has had a chance to call it bac/ toresolve OXIDI.

La8y -!e Prot!e9

In a homogeneous network, all machines communication via the same protocol sequence. In aheterogeneous network, machines may support multiple protocol sequences. Since it is often expensive in

resources to allocate endpoints (RpcSer@erUseProtse) for all available protocol sequences, ORPC provides amechanism where they may be allocated on demand. To implement this extension fully, there are somechanges in the server. However, changes are optional. If not implemented, ORPC will still work correctlyif less optimally in heterogeneous networks.

There are two cases: the server implements the lazy use protocol or it does not.



21/27


If the server is using the lazy use protseq protocol, the use of Reso(@eOx+' is modified slightly. When theclient OX calls the server OX, it passes the requested protseq vector. If none of the requested protseqshave 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 serverand contain complete endpoints. However, if they are not, the endpoint mapper can be used to forwardcalls to the server. This requires that all server IIDsare registered in the endpoint mapper. It also allows a

different lazy use protseq mechanism. The endpoint mapper can perform some local magic to force theserver 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 notimplement 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 stringbindings for all processes that are ORPC servers on its machines. However, unless the middle manmarshaler 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 areference 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 withthat 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

[idepotent error_%tatu%_t /iple.in8 ( [in andle_t hRpc, [in /:&* OpSetId )

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 ithas recently been pin#ed. S+p(eP+n, just pin#s the contents of a set. &he set must be created withCop(exP+n,(see below".

in# a set, previously created with IObjectExporter))Cop(exP+n,, of OIDs owned by this Object 6porter. 4otethat neither IPIDs nor OIDs may be pin#ed, only eplicitly created SETIDs.


/Rpc /an'(e2t $n 'C bindin# handle used to ma/e the re5uest.

pSetI' SETID9 $ SETIDpreviously created with IObjectExporter))Cop(exP+n,on thissame Object 6porter.

Return Value MeaninS2O 7uccess. &he set was pin#ed.RPC2E2I43A6ID2SET &his SETID is un/nown to this Object 6porter, and thus the pin# did not occur.E2U4EXPECTED $n unspecified error occurred. It is not /nown whether the pin# was done or not.

.Object&1porter::Comple1Pin

[idepotent error_%tatu%_t ople.in8 ( [in andle_t hRpc, [in /:&* OpSetId, [in un%i8ned %ort SequenceNum, [in un%i8ned %ort SetPingPeriod, [in un%i8ned %ort SetNumPingsToTimeout, [out un%i8ned %ort OpReqSetPingPeriod, [out un%i8ned %ort OpReqSetNumPingsToTimeout, [in un%i8ned %ort cAddToSet, [in un%i8ned %ort cDelromSet, [in, unique, %iMe_i%(c


22/27


in# a pin# set. Optionally, add and 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 contentsof the set as active. $fter a set is defined, S+p(eP+n,should be used to pin# the set. Cop(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 6porter. &he client Object 6porter thencommunicates with the server Object 6porter to add (and later remove" OIDsfrom the pin# set. Clientsmust ensure the SETIDspin#ed at a #iven server are uni5ue over all of that serverDs clients. &hus, theclient must only use SETIDs that it /nows not to be in use as SETIDsby other clients on that server. (In

practice, clients allocate SETIDs as #lobally uni5ue". $ client may use as many sets as it li/es, thou#husin# fewer sets is more efficient.

6ach OID owned by a server Object 6porter may be placed in =ero or more pin# sets by the various clientsof 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 toit. &he server Object 6porter is responsible for ensurin# that an OID that it owns does not epire until atleast a period of time thas elapsed without that OIDbein# pin#ed, where tis the maimum time-out periodover all the sets which presently contain the #iven OID, or, if OID is not presently in any such sets but was

previously, tis the time-out period for the last set from which OID was removed at the instant that thatremoval was done1>otherwise, OID has never been in a set, and tis a default value (&A*".

Clients are responsible for pin#in# servers often enou#h to ensure that they do not epire #iven the

possibility of networ/ delays, lost pac/ets, and so on. If a client only re5uires access to a #iven object forwhat it would consider less than a time-out period for the object (that is, it receives and release the objectin 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 Cop(exP+n, that both adds and removes the OI* will suffice".&his ensures that an object will not epire as it is passed throu#h a chain of calls from one client toanother.

$n OID is said to be pin#ed when a set into which it was previously added and presently still resides ispin#ed with either a S+p(eP+n, or a Cop(exP+n,, or when it is newly added to a set with Cop(exP+n,. 4otethat these rules imply that a Cop(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 newly-specified pin# period and a newly-specified pin# count to epiration! these values ta/e effectimmediately. in# periods are specified in tenths of a second, yieldin# a maimum allowable pin# periodof about 1 hr 3? min. $djustment of the time-out period of the set is considered to happen before the

addition of any new OIDsto the set, which is in turn considered to happen before the removal of any OIDsfrom the set. &hus, an OID that is added and removed in a sin#le call no lon#er resides in the set, but isconsidered to have been pin#ed, and will have as its time-out at least the time-out period specified in thatCop(exP+n, call.

On eit, the server may re5uest that the client adjust the time-out period that is, as/ it to specify adifferent time-out period in subse5uent calls to Cop(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 thevariables pReSetP+n,Per+o' and pReSet4uP+n,sToT+eOut.If the server see/s no chan#e, it simply returnsthe correspondin# values passed by the client if it wishes a lon#er time-out period, it indicates lar#ervalues for one or both of these variables if it wishes a smaller period, it indicates smaller values. +henindicatin# a lar#er value, the server must start immediately actin# on that lar#er value by adjustin# thetime-out period of the set. However, when indicatin# a smaller value, it must consider its re5uest as purelyadvice to the client, and not ta/e any action% if the client wishes to obli#e, it will do so in a subse5uent callto Cop(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.

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


23/27




pSetI' SETID &he SETIDbein# manipulated.

Seuence4u USHORT &he se5uence number allows the object eporter to detect duplicatepac/ets. 7ince the call is +'epotent, it is possible for duplicates to#et eecuted and for calls to arrive out of order when one pin# is

delayed.

SetP+n,Per+o' USHORT Thi! parameter i! oin away5

Set4uP+n,sToT+eOut USHORT Thi! parameter i! oin away.

pReSetP+n,Per+o' USHORT9 Thi! parameter i! chanin. &he server uses pReSetP+n,Per+o'tore5uest a new pin# period. If the re5uested period is shorter thenthe current period, the server must continue to use the current

period until the client calls bac/. +hen the client calls bac/ theold re5uested period will only be used if the client specifies it as thenew 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 net call will containthe old, shorter period.

pReSet4uP+n,sToT+eOut USHORT9 Thi! parameter i! chanin. &he server usespReSet4uP+n,sToT+eoutto re5uest a new number of pin#s. If thenumber of pin#s is less then the current number of pin#s, the servermust continue to use the current number of pin#s until the clientcalls bac/. +hen the client calls bac/ the old re5uested period willonly be used if the client specifies it as the newSet4uP+n,sToT+eout. If the re5uested number of pin#s is lar#erthen the current number of pin#s, the server must immediately

bein# usin# the new number of pin#s. However, if the clientdoesnDt accept it, the net call will contain the old, smaller numberof pin#s.

cA''ToSet USHORT &he si=e of the array A''ToSet.

cDe(&roSet USHORT &he si=e of the array De(&roSet.

A''ToSet OID- &he list of OIDswhich are to be added to this set. $ddin# an OID toa set in which it already eists is permitted such an action, aswould be epected, is considered to pin# the OID.

De(&roSet OID- &he list of OIDswhich are to be removed from this set. 'emovalcounts as a pin#. $n IPIDremoved from a set will epire after thenumber of pin# periods has epired without any pin#s (not thenumber of pin# periods - 1". If an id is added and removed from aset in the same Cop(exP+n,, the id is considered to have beendeleted.

Return Value MeaninS2O 7uccess. &he set was pin#ed, etc.RPC2E2I43A6ID2O$%ECT Indicates that some OIDwas not reco#ni=ed. &here is no recovery action for this

error, it is informational only.RPC2E2ACCESS2DE4IED

RPC2E2OUT2O&2ORDER 'eturned when a call is received with a se5uence number which is less then thelast se5uence number eecuted successfully.

E2OUTOE#OR7 &here was not enou#h memory to service the call. &he caller may retry addin#OIDsto the set on the net pin#.

E2U4EXPECTED $n unspecified error occurred. It is not /nown whether the pin# or any of the otheractions were done or not.

Secur+ty re(ate' errors &A*

DRAFT Page ', Cop!right " 1##5 Micro$oft CorporationAll Right$ Re$er%e&


24/27


)ervice Control Manaer

&he 7ervice Control Mana#er (7CM" is the component of the COM )ibrary responsible for locatin# classimplementations and runnin# them. &he 7CM ensures that when a client re5uest is made, the appropriateserver is connected and ready to receive the re5uest. &he 7CM /eeps a database of class information basedon 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 servicesreside at the same well-/nown endpoints as the COM Object 6porter1@on each machine. 4ote that unli/e

the Object 6porter service, which is re5uired for a machine to epose COM objects remotely, the eposed7CM service is in fact optionaland some machines may not offer it. Clients may receive references to

eistin# objects on such a machine or cause objects to be instantiated on that machine throu#h meansbesides 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 classfactory returned to the COM )ibrary. $fter that, the COM )ibrary, or the client, can as/ the class factoryto 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 serverimplementation. &he COM library then loads the *)) and as/s it forits class factory interface pointer.

Local &he 7CM starts the local eecutable which re#isters a class factory on

startup. &hat pointer is then available to COM.%emote &he local 7CM contacts the 7CM runnin# on the appropriate remote

machine and forwards the re5uest to the remote 7CM. &he remote7CM launches the server which re#isters a class factory li/e the localserver with COM on that remote machine. &he remote 7CM thenmaintains a connection to that class factory and returns an 'Cconnection to the local 7CM which corresponds to that remote class

13 4ot surprisin#ly, to #et around the chic/en and e## problem, #ettin# to a remote machineDs 7CM interface is not done vianormal CoCreateInstancemeans. 'icher mechanisms for creatin# an interface to a remote 7CM are &A*, but note that the clarity aboutthe 7CM-to-7CM interface and its endpoints ensure interconnectivity.

1@ &his is true despite final word whether the Object 6porter will reuse the *C6 'C 6ndpoint MapperDs endpoints or adifferent well-/nown set &A*, as noted above.

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

C(+ent

App(+cat+on

Local

Object

Proxy

Remote

Object

Proxy

COM

RPC Connection

to Remote Server

RPC Connection

to Local Server

(1) Client:

Create

an Object

SCM:

6ocates1runs ser@ers1

J>K LHereMs your

Connect+onN

() COM: !in"

a Server#n$Proce%%

Object

Local

Object

Remote

Object

(&) COM:

'ere% your

ointer

*%+ remote SCM

to launc, alication

Launc, alication

'i"re 474: COM deleate! re!pon!ibility o/ loadin and la"nchin !erver! to the )CM5


25/27


factory. &he local 7CM then returns that connection to COM whichcreates a class factory proy which will internally forward re5uests tothe remote 7CM via the 'C connection and thus on to the remoteserver.

4ote that if the remote 7CM determines that the remote server is actually an in-process server, it launchesa 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*)"%

P------------------------------------------------------------------------- icro%oft Kindo% op'ri8t () icro%oft orporation, 1992 - 1995 CileL %c%cidl /'nop%i%L nterface for / to / counication &i% i% te interface tat need% to be %upported b' o%t% tat allo actiGation of ob"ect% !nl' one in%tance of ti% interface can be eported b' te o%t--------------------------------------------------------------------------

[ uuid(00000137-0000-0000-000-000000000046), Ger%ion(10), pointer_default(unique)

interface /to/

B#:/F=&


26/27




orpct/+s ORPCTHIS9 ORPCTHISidentifyin# this object.

orpct/at ORPCTHAT9 ORPCTHATholdin# return values.

rc(s+' C6SID9 Identifies the class to be run to service the re5uest.

p"s8Object4ae CHAR9 Identifies the persistent representation of the object to thismachine. &ypically, this is a file name which is used to determinethe class, as in Create&+(e#on+!erJp"s8&+(e4ae1 p!Kfollowed by$+n'#on+!erJp!K.

c(sctx DORD alues ta/en from the C6SCTXenumeration.

,rf#o'e DORD alues ta/en from the ST*#enumeration.

'"Count DORD &he number of interfaces to return.

pIIDs IID9 $n array of interfaces to QueryInterfacefor on the new object.

ppInterfaces O$%RE&99 )ocation to return an array of interfaces on the object.

pResu(ts HRESU6T9)ocation to return an array of return codes about the successfulretrieval of each of the '"Countinterfaces.

Return Value MeaninS2O

7uccess.CO2S24OTA66I4TER&ACES 7ome but not all of the '"Countinterfaces were returned in ppInterface*ata.6amine pResu(tsto identify eactly which interf

6rappin DC& %PC call! to interoperate with O%PC

&his is an eample of a server side wrapper for the Aar method. It assumes the eistence of small helperfunctions to import and eport object references and loo/up previously eported object references.

RPC2STATUS $arJ/an'(e2t /1 s/ort +1 O$%RE& 9 prI$1 O$%RE& 99 pprIK UUID +p+'

RPC2STATUS statusI&oo 9 pI&I$ar 9 pI$Ia8 9 PIHRESU6T /R

status Rpc$+n'+n,InObjectJ/1 +p+'K+f JstatusK returnJSO#ETHI4*K

status ORpc6oo!upIPIDJ+p+'1 pI&K+f JstatusK returnJSO#ETHI4*K

status ORpcIportObjRefJprI$1 pI$K+f JstatusK returnJSO#ETHI4*K

/R pI&0F$arJ+1 pI$1 pIK actua( ca(( to t/e et/o'

pI$0FRe(easeJKstatus ORpcExportObjRefJpI1 pprIKreturnJ/R /R ) SO#ETHI4*K

&his is an eample of the client side wrapper for Aar%

assue soe c(ass C&oo t/at +p(eents $ar et/o'c(ass C&oo ) IUn!no"n1 I&oo UUID +p+' one for eac/ +nterface/an'(e2t /

@+rtua( HRESU6T QueryInterfaceJUUID ++'1 @o+' 99pp@o+'K@+rtua( HRESU6T A''RefJK@+rtua( HRESU6T Re(easeJK@+rtua( HRESU6T $arJs/ort +1 I&oo 9 pI&1 Ia8 99 ppIK

HRESU6T C&oo))$arJs/ort +1 I&oo 9 pI&1 Ia8 99 ppIK O$%RE& 9 prI&O$%RE& 9 prI



27/27


HRESU6T /RRPC2STATUS status

status Rpc$+n'+n,SetObjectJt/+s0F/1 t/+s0F+p+'K+f JstatusK returnJSO#ETHI4*K

status ORpcExportObjRefJpI&1 prI&K+f JstatusK returnJSO#ETHI4*K

/R $arJt/+s0F/1 +1 prI&1 prIK

status ORpcIportObjRefJprI1 ppIK

ORpc&reeObjRefJprI&KORpc&reeObjRefJprIK

returnJ/R /R ) SO#ETHI4*K

.mplementin O%PC in %PC

Since the implicit parameters are specified as IDL, the ORPC header received by RPC will contain manyfields inserted by MIDL. Here are the definitions for the header on the wire.

9

An +nboun' /ea'er "ou(' be (a+' out as fo((o"s "/ere t/eextent array +s opt+ona( an' t/ere ay be 8ero of ore extents.An outboun' /ea'er +s (a+' out s++(ar(y.

ORPCTHIS2ITH4OEXTE4SIO4S-ORPC2EXTE4T2ARRA7

-ORPC2EXTE4T9

9type'ef struct CO#3ERSIO4 @ers+on CO# @ers+on nuber uns+,ne' (on, f(a,s I4&O f(a,s for presence of ot/er 'ata uns+,ne' (on, reser@e': set to 8ero 6TID (t+' (o,+ca( t/rea' +' of ca((er uns+,ne' (on, un+ue ta, to +n'+cate presence of extens+ons ORPCTHIS2ITH4OEXTE4SIO4

type'ef struct uns+,ne' (on, roun'e'2s+8e Actua( nuber of extents. uu+'2t +' Extens+on +'ent+f+er. uns+,ne' (on, s+8e Extens+on s+8e. byte 'ata- Extens+on 'ata. ORPC2EXTE4T

Array of extens+ons.type'ef struct uns+,ne' (on, roun'e'2s+8e Actua( nuber of extents uns+,ne' (on, s+8e 4uber of extents uns+,ne' (on, un+ue2f(a,- &(a,s to +n'+cate presense of ORPC2EXTE4Ts ORPC2EXTE4T2ARRA7

type'ef struct uns+,ne' (on, f(a,s I4&O f(a,s for presence of ot/er 'ata uns+,ne' (on, un+ue ta, to +n'+cate presence of extens+ons ORPCTHAT2ITH24OEXTE4SIO4S

&his pa#e intentionally left blan/.

CH15 Network Protocol.doc

Documents

Transcript of CH15 Network Protocol.doc