OBJREF

An OBJREF is the data type used to represent an actual marshaled object reference. An OBJREF can either be empty or assume one of five variations, depending on the degree to which the object being marshaled uses the hook architecture (IMarshal, and so forth) in the marshaling infrastructure. The OBJREF structure is a union consisting of a switch flag followed by the appropriate data.

OBJREF_STANDARD

Contains one interface of an object marshaled in standard form. The data that follows the switch flag is a STDOBJREF structure (described below).

OBJREF_HANDLER

A marshaling of an object that wants to use handler marshaling. For example, an object wants to be represented in client address spaces by a proxy object that caches state. In this case, the class-specific information is just a standard reference to an interface pointer that the handler (proxy object) will use to communicate with the original object. See the IStdMarshalInfo interface.

Member

Type

Semantic


std

STDOBJREF

A standard object reference used to connect to the source object.

Clsid

CLSID

The CLSID of handler to create in the destination client.


OBJREF_LONGSTD

An interface marshaled on an object in long form. Contains a standard reference, along with a set of protocol sequences and network addresses that can be used to bind to an OXID resolver that is able to resolve the OXID in the STDOBJREF. This is useful when marshaling a proxy to give to another computer (a.k.a. the middleman case). The marshaling computer can specify the saResAddr for the resolver on the server computer so that the unmarshaler does not need to call the marshaler (middleman) back to get this information. Further, the marshaler does not need to keep the OXID in its cache beyond the lifetime of its own references in order to satisfy requests from parties that it just gave the OBJREF to.

Member

Type

Semantic


std

STDOBJREF

A standard object reference used to connect to the source object.

SaResAddr

STRINGARRAY

The resolver address.


OBJREF_LONGHDLR

Contains the same information as the handler case as well as the object resolver address. This form is needed for the same reason OBJREF_LONGSTD is needed.

Member

Type

Semantic


std

STDOBJREF

A standard object reference used to connect to the source object.

Clsid

CLSID

The class ID of the handler.

SaResAddr

STRINGARRAY

The resolver address.


OBJREF_CUSTOM

A marshaling of an object which supports custom marshaling. The Custom format gives an object control over the representation of references to itself. For example, an immutable object might be passed by value, in which case the class-specific information would contain the object's immutable data. See the IMarshal interface.

Member

Type

Semantic


clsid

CLSID

The CLSID of the object to create in the destination client.

size

unsigned long

The size of the marshaled data provided by the source object and passed here in pData.

pData

byte*

The data bytes that should be passed to IMarshal::UnmarshalInterface on a new instance of class clsid in order to initialize it and complete the unmarshal process.


STDOBJREF

An instance of a STDOBJREF represents a COM interface pointer that has been marshaled using the standard COM network protocol. A STDOBJREF in general can only be interpreted in the context of an outstanding ORPC, for it may contain an OXID unknown to the computer on which it is unmarshaled, and it is the only computer which is making [an] outstanding call which is guaranteed to be able to provide the binding information for the OXID.

The members and semantics of the STDOBJREF structure are as follows:

Member

Semantic


flags

Flag values taken from the enumeration SORFFLAGS. These are described below.

Crefs

The number of reference counts on ipid that being transferred in this marshaling.

Ipid

The IPID of the interface being marshaled.

Oid

The OID of the object to which ipid corresponds.

Oxid

The OXID of the server that owns this OID.


The various SORFLAGS values have the following meanings. The SORF_OXRESx bit flags are reserved for the object exporter's use only, and must be ignored by object importers. They need not be passed through when marshaling an interface proxy.

Flag

Value

Meaning


SORF_NOPING

1

This OID does not require pinging. Further, all interfaces on this OID, including this IPID, need not be reference counted. Pinging and reference counting on this object and its interfaces are still permitted, however, though such action is pointless.

SORF_OXRES1

8

Reserved for exporter.

SORF_OXRES2

16

Reserved for exporter.

SORF_OXRES3

32

Reserved for exporter.

SORF_OXRES4

64

Reserved for exporter.


ORPCTHIS

In every Request PDU that is an ORPC, the body (CL case) or the stub data (CO case) which normally contains the marshaled arguments in fact begins with an instance of the ORPCTHIS structure. The marshaled arguments of the COM interface invocation follow the ORPCTHIS; thus, viewed at the DCE RPC perspective, the call has an additional first argument. The ORPCTHIS is padded with zero bytes if necessary to achieve an overall size that is a multiple of eight bytes; thus, the remaining arguments are as a whole eight-byte aligned.

As in regular calls, the causality ID must be propagated. If A calls ComputePi on B, B calls Release on C (which gets converted to RemRelease), and C calls Add on A, A will see the same causality ID that it called B with.

Member

Type

Semantic


version

COMVERSION

The version number of the COM protocol used to make this particular ORPC. The initial value will be 1.1. Each packet contains the sender's major and minor ORPC version numbers. The client's and server's major versions must be equal. Backward-compatible changes in the protocol are indicated by higher minor version numbers. Therefore, a server's minor version must be greater than or equal to the client's. However, if the server's minor version exceeds the client's minor version, it must return the client's minor version and restrict its use of the protocol to the minor version specified by the client. A protocol version mismatch causes the RPC_E_VERSION_MISMATCH ORPC fault to be returned.

flags

unsigned long

Flag values taken from the enumeration ORPCINFOFLAGS. These are elaborated below.

reserved

unsigned long

Must be set to zero.

cid

CID

The causality ID of this ORPC. See comments below.

extensions

ORPC_EXTENT_ARRAY*

The body extensions, if any, passed with this call. Body extensions are GUID-tagged blobs of data which are marshaled as an array of bytes. Extensions are always marshaled with initial eight-byte alignment. Body extensions which are presently defined are described below.


The various ORPCINFOFLAGS have the following meanings.

Flag

Meaning


INFO_NULL

(Not a real flag. Merely a defined constant indicating the absence of any flag values.)

INFO_LOCAL

The destination of this call is on the same computer on which it originates. This value is never to be specified in calls which are not in fact local.

INFO_RESERVED1

If INFO_LOCAL is set, then reserved for local use; otherwise, reserved for future use.

INFO_RESERVED2

If INFO_LOCAL is set, then reserved for local use; otherwise, reserved for future use.

INFO_RESERVED3

If INFO_LOCAL is set, then reserved for local use; otherwise, reserved for future use.

INFO_RESERVED4

If INFO_LOCAL is set, then reserved for local use; otherwise, reserved for future use.


Implementations may use the local and reserved flags to indicate any extra information needed for local calls. Note that if the INFO_LOCAL bit is not set and any of the other bits are set, then the receiver should return a fault.

Comments }3 The cid field contains the causality ID.11. Each time a client makes a call, a new causality ID is generated. If a server makes a call while processing a request from a client, the new call must have the same causality ID. This allows simple servers to avoid working on more then one thing at a time (for example: A calls B calls A again, meanwhile C tries to call A with a new causality ID). It tells the server that he is being called because he asked someone to do something for him. There are several interesting exceptions:

The extensions field contains extensions to the channel header. Two are currently defined for Microsoft's implementation of this protocol (described below). Other implementations may define their own extensions with their own UUIDs. Implementations should skip over extensions they do not recognize or wish to support. Note that in order to force the ORPCTHIS header to be eight-byte aligned, an even number of extensions must be present and the size of the extension data must be a multiple of eight.

ORPCTHAT

In every Response PDU that is an ORPC, the body (CL case) or the stub data (CO case) which normally contains the marshaled output parameters in fact begins with an instance of the ORPCTHAT structure. The marshaled output parameters of the COM interface invocation follow the ORPCTHAT; thus, viewed at the DCE RPC perspective, the call has additional output parameters. The ORPCTHAT is padded with zero-bytes if necessary to achieve an overall size that is a multiple of eight bytes; thus, the remaining output parameters as a whole [are] eight-byte aligned.

Member

Type

Semantic


flags

unsigned long

Flag values taken from the enumeration ORPCINFOFLAGS. These are elaborated above.

extensions

ORPC_EXTENT_ARRAY*

The body extensions, if any, returned by this call. Body extensions are GUID-tagged blobs of data which are marshaled as an array of bytes. Extensions are always marshaled with initial eight-byte alignment.