{"id":533,"date":"2014-07-10T07:00:00","date_gmt":"2014-07-10T07:00:00","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/oldnewthing\/2014\/07\/10\/using-the-refiidvoid-pattern-for-returning-com-objects-for-future-proofing-and-to-avoid-problems-with-dependencies\/"},"modified":"2014-07-10T07:00:00","modified_gmt":"2014-07-10T07:00:00","slug":"using-the-refiidvoid-pattern-for-returning-com-objects-for-future-proofing-and-to-avoid-problems-with-dependencies","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/oldnewthing\/20140710-00\/?p=533","title":{"rendered":"Using the REFIID\/void** pattern for returning COM objects for future-proofing and to avoid problems with dependencies"},"content":{"rendered":"

\nSuppose you have a function that creates a reference to a COM object:\n<\/p>\n

\n\/\/ pixie.h\nSTDAPI CreateShellItemFromPixieDust(\n    const PIXIEDUST *ppd,\n    IShellItem **ppsi);\n<\/pre>\n
\nThere are a few issues with this design.\n<\/p>\n
\nFirst of all, it requires that whoever uses your header file\nmust have included shlobj.h<\/code> first,\nsince that’s where IShell­Item<\/code> is defined.\nYou could solve that problem by putting\n#include <shlobj.h><\/code> at the top of\npixie.h<\/code>,\nbut that creates its own problems.\nFor example, many header files alter their behavior based\non symbols that have been #define<\/code>d,\nand including that other header file as part of\npixie.h<\/code> means that it’s going to use the settings\nthat were active at the time pixie.h<\/code> was included\n(which may not be what the clients of your header file are expecting).\nFor example:\n<\/p>\n
\n#include <windows.h>\n#include <ole2.h>\n#include <pixie.h>\n#define STRICT_TYPED_ITEMIDS<\/a>\n#include <shlobj.h>\n<\/pre>\n
\nThis program wants to use strict typed item IDs,\nso it defines the magic symbol before including\nshlobj.h<\/code>.\nUnfortunately, that request is ignored because\nthe pixie.h<\/code> header file secretly included\nshlobj.h<\/code> prematurely.\n<\/p>\n
\nThis can get particularly messy if somebody wants to\ninclude shlobj.h<\/code> with particular preprocessor\ntricks temporarily active.\n<\/p>\n
\n#include <windows.h>\n#include <ole2.h>\n#include <pixie.h>\n\/\/ The WINDOWDATA structure added in Windows Vista conflicts\n\/\/ with the one we defined back in 2000, so rename it to\n\/\/ WINDOWDATA_WINDOWS.\n#define WINDOWDATA WINDOWDATA_WINDOWS\n#include <shlobj.h>\n#undef WINDOWDATA\n\/\/ Here's our version of WINDOWDATA\n#include <contosotypes.h>\n<\/pre>\n
\nThis code works around a naming conflict that was created\nwhen Windows Vista added a structure called\nWINDOW­DATA<\/code> to shlobj.h<\/code>.\nThe application already had a structure with the same name,\nso it has to rename the one in shlobj.h<\/code> to\nsome other name to avoid a redefinition error.\n<\/p>\n
\nIf you made pixie.h<\/code> include\nshlobj.h<\/code> on its own,\nit would do so without this fancy renaming, and the\ndevelopers of that code will curse and say something like this:\n<\/p>\n
\n#include <windows.h>\n#include <ole2.h>\n\/\/ The WINDOWDATA structure added in Windows Vista conflicts\n\/\/ with the one we defined back in 2000, so rename it to\n\/\/ WINDOWDATA_WINDOWS.\n#define WINDOWDATA WINDOWDATA_WINDOWS\n\/\/ pixie.h secretly includes shlobj.h so we have to put its #include\n\/\/ under WINDOWDATA protection.\n#include <pixie.h><\/font>\n#include <shlobj.h>\n#undef WINDOWDATA\n\/\/ Here's our version of WINDOWDATA\n#include <contosotypes.h>\n<\/pre>\n
\nAnother problem with the\nCreate­Shell­Item­From­Pixie­Dust<\/code>\nfunction is that it hard-codes the output interface to\nIShell­Item<\/code>.\nWhen everybody moves on to\nIShell­Item2<\/code>,\nall the callers will have to\nfollow the\nCreate­Shell­Item­From­Pixie­Dust<\/code>\ncall with a Query­Interface<\/code> to get the interface\nthey really want.\n(Which, if your object is out-of-process,\ncould mean another round trip to the server.)\n<\/p>\n
\nThe solution to both of these problems is to simply make the\ncaller specify what type of object they want.\n<\/p>\n
\n\/\/ pixie.h\nSTDAPI CreateShellItemFromPixieDust(\n    const PIXIEDUST *ppd,\n    REFIID riid,\n    void **ppv);\n<\/pre>\n
\nNow that we are no longer mentioning\nIShell­Item<\/code> explicitly,\nwe don’t need to include shlobj.h<\/code> any more.\nAnd if the caller wants IShell­Item2<\/code>,\nthey can just ask for it.\n<\/p>\n
\nYour creation function used to look like this:\n<\/p>\n
\nSTDAPI CreateShellItemFromPixieDust(\n    const PIXIEDUST *ppd,\n    IShellItem **ppsi)\n{\n    *ppsi = nullptr;\n    IShellItem *psiResult;\n    HRESULT hr = ... do whatever ...;\n    if (SUCCEEDED(hr))\n    {\n       *ppsi = psiResult;\n    }\n    return hr;\n}\n<\/pre>\n
\nYou simply have to tweak the way you return the pointer:\n<\/p>\n
\nSTDAPI CreateShellItemFromPixieDust(\n    const PIXIEDUST *ppd,\n    REFIID riid,\n    void **ppv<\/font>)\n{\n    *ppv = nullptr;\n    IShellItem *psiResult;\n    HRESULT hr = ... do whatever ...;\n    if (SUCCEEDED(hr))\n    {\n       hr = psiResult->QueryInterface(riid, ppv);\n       psiResult->Release();<\/font>\n    }\n    return hr;\n}\n<\/pre>\n
\nCallers of your function would go from\n<\/p>\n
\nIShellItem *psi;\nhr = CreateShellItemFromPixieDust(ppd, &psi);\n<\/pre>\n
\nto\n<\/p>\n
\nIShellItem *psi;\nhr = CreateShellItemFromPixieDust(ppd, IID_PPV_ARGS(&psi)<\/font>);\n<\/pre>\n
\nIf the caller decides that they really want an\nIShell­Item2<\/code>,\nthey merely have to change their variable declaration;\nthe call to the creation function is unchanged.\n<\/p>\n
\nIShellItem2 *psi;<\/font>\nhr = CreateShellItemFromPixieDust(ppd, IID_PPV_ARGS(&psi));\n<\/pre>\n","protected":false},"excerpt":{"rendered":"
Suppose you have a function that creates a reference to a COM object: \/\/ pixie.h STDAPI CreateShellItemFromPixieDust( const PIXIEDUST *ppd, IShellItem **ppsi); There are a few issues with this design. First of all, it requires that whoever uses your header file must have included shlobj.h first, since that’s where IShell­Item is defined. You could solve […]<\/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-533","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-oldnewthing","tag-code"],"acf":[],"blog_post_summary":"
Suppose you have a function that creates a reference to a COM object: \/\/ pixie.h STDAPI CreateShellItemFromPixieDust( const PIXIEDUST *ppd, IShellItem **ppsi); There are a few issues with this design. First of all, it requires that whoever uses your header file must have included shlobj.h first, since that’s where IShell­Item is defined. You could solve […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/533","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=533"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/533\/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=533"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/categories?post=533"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/tags?post=533"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}