{"id":106750,"date":"2022-06-14T07:00:00","date_gmt":"2022-06-14T14:00:00","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/oldnewthing\/?p=106750"},"modified":"2022-06-14T05:58:45","modified_gmt":"2022-06-14T12:58:45","slug":"20220614-00","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/oldnewthing\/20220614-00\/?p=106750","title":{"rendered":"What are the various usage patterns for manually-marshaled interfaces?"},"content":{"rendered":"

COM organizes threads into apartments<\/i>. All the thread in an apartment have access to the same objects, and if you want to grant access to another apartment, you have to do it by a mechanism known as marshaling<\/i>.<\/p>\n

The easiest way to marshal an object’s interface is to ask somebody else to manage it for you: The Ro\u00adGet\u00adAgile\u00adReference<\/code> function creates a new object that represents an agile reference<\/i> to the original object. In COM, the term agile<\/i> means that it can be used in any apartment. You can then ask that agile reference to resolve<\/i> a reference to the original interface, and it will give you an object which you can use from the apartment doing the resolving.<\/p>\n

Bonus reading<\/b>: When should I use delayed-marshaling when creating an agile reference<\/a>?<\/p>\n

A lower-level method is to use Co\u00adMarshal\u00adInter\u00adThread\u00adInterface\u00adIn\u00adStream<\/code> to take an object interface and save it into a byte stream. That stream is a magic cookie that can be used to recover the original interface from any apartment. And since it’s a stream of bytes, you have any number of ways of sharing those bytes with another thread: You could save them in a global variable, you could write them to a named pipe, or you could print them on a piece of paper, bury it in the ground, then come back and dig up the paper and OCR the digits. Whatever the mechanism, you can pass the bytes to Co\u00adUnmarshal\u00adInterface<\/code> (or its own helper function Co\u00adGet\u00adInterface\u00adAnd\u00adRelease\u00adStream<\/code>) and it will produce an object that you can use.<\/p>\n

But we’re going to look at what happens at an even lower level: The Co\u00adMarshal\u00adInterface<\/code> function is the one that generates the stream. In addition to the obvious parameters (the stream to which to write the bytes, the interface being marshaled, and an interface pointer), there are two somewhat more mysterious parameters: The destination context and the marshal flags.<\/p>\n

The destination context describes where<\/i> you intend to unmarshal the object. Here are the destination contexts in order of distance from the source:<\/p>\n\n\n\n\n\n\n\n\n
Flag<\/th>\nMeaning<\/th>\nGroup<\/th>\n<\/tr>\n
MSHCTX_CROSSCTX<\/code><\/td>\nAnother context in the same apartment.<\/td>\nSame-process<\/td>\n<\/tr>\n
MSHCTX_INPROC<\/code><\/td>\nAnother apartment in the same process.<\/td>\n<\/tr>\n
MSHCTX_LOCAL<\/code><\/td>\nAnother process on the same computer
\nwhich can share memory with the source.<\/td>\n		Same-machine<\/td>\n<\/tr>\n
MSHCTX_NOSHAREDMEM<\/code><\/td>\nAnother process on the same computer
\nwhich cannot share memory with the source.<\/td>\n<\/tr>\n
MSHCTX_DIFFERENT\u00adMACHINE<\/code><\/td>\nAnother computer.<\/td>\nCross-machine<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

Marshaling across integrity levels would be a case where the source and destination processes cannot share memory.<\/p>\n

Although there are five different marshaling contexts, most marshaling code cares only about which group they belong to: The same-process group (CROSSCTX<\/code> and INPROC<\/code>) the same-machine group (LOCAL<\/code> and NOSHAREDMEM<\/code>) and the cross-machine group (DIFFERENT\u00adMACHINE<\/code>).<\/p>\n

Meanwhile, the marshal flags describe how<\/i> you intend to unmarshal the object.<\/p>\n\n\n\n\n\n\n
Flag<\/th>\nNumber of times to unmarshal<\/th>\nStrong or weak reference<\/th>\n<\/tr>\n
MSHLFLAGS_NORMAL<\/code><\/td>\nExactly once.<\/td>\nStrong<\/td>\n<\/tr>\n
MSHLFLAGS_TABLESTRONG<\/code><\/td>\nAny number of times (possibly zero).<\/td>\nStrong<\/td>\n<\/tr>\n
MSHLFLAGS_TABLEWEAK<\/code><\/td>\nAny number of times (possibly zero).<\/td>\nWeak<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

The first case is called “normal” because it is the most common case of marshaling: You have a single reference that you want to transfer to another apartment. We’ll see that knowing in advance that this is how you intend to marshal the object interface allows for some optimizations.<\/p>\n

The last two cases are for where the object can be unmarshaled any number of times (possibly zero). They differ in whether the stream itself keeps the object alive.<\/p>\n

The marshal flags control the usage pattern for managing the stream.<\/p>\n

If you choose either of the “table” (reusable) marshaling flags, the sequence is<\/p>\n

    \n
  • Call Co\u00adMarshal\u00adInterface<\/code> to write the bytes to the stream.<\/li>\n
  • Call Co\u00adUnmarshal\u00adInterface<\/code> to produce an object from the stream. Repeat this as many times as you like, or skip it entirely.<\/li>\n
  • Call Co\u00adRelease\u00adMarshal\u00adData<\/code> to signal that you are not going to be unmarshaling from the stream any more.<\/li>\n<\/ul>\n

    The difference between the two “table” versions is whether the stream itself keeps the object alive. If you choose a weak reference, then it is your responsibility not to call Co\u00adUnmarshal\u00adInterface<\/code> once the object has been destroyed. (Typically, you accomplish this by ensuring that the stream’s lifetime is encompassed by the object’s lifetime.)<\/p>\n

    If you choose “normal” (one-time) marshaling, the sequence is<\/p>\n

      \n
    • Call Co\u00adMarshal\u00adInterface<\/code> to write the bytes to the stream.<\/li>\n
    • Either\n
        \n
      • Call Co\u00adUnmarshal\u00adInterface<\/code> to produce an object from the stream, or<\/li>\n
      • Call Co\u00adRelease\u00adMarshal\u00adData<\/code> to abandon the operation.<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n

        In the case of “normal” marshaling, once you call Co\u00adUnmarshal\u00adInterface<\/code> or Co\u00adRelease\u00adMarshal\u00adData<\/code>, the stream can no longer be used further. Conceptually, you can imagine that calling Co\u00adUnmarshal\u00adInterface<\/code> “normal” marshaling is like “table strong” marshaling, with the added feature that the Co\u00adUnmarshal\u00adInterface<\/code> implicitly performs a Co\u00adRelease\u00adMarshal\u00adData<\/code> when it’s done.<\/p>\n

        Next time, we’ll start looking at the mechanics of how COM marshaling is performed.<\/p>\n","protected":false},"excerpt":{"rendered":"

        The outermost simple layer, and the more complex inner layer.<\/p>\n","protected":false},"author":1069,"featured_media":111744,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[25],"class_list":["post-106750","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-oldnewthing","tag-code"],"acf":[],"blog_post_summary":"

        The outermost simple layer, and the more complex inner layer.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/106750","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/users\/1069"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/comments?post=106750"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/106750\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media\/111744"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media?parent=106750"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/categories?post=106750"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/tags?post=106750"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}