{"id":44023,"date":"2014-09-19T07:00:00","date_gmt":"2014-09-19T07:00:00","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/oldnewthing\/2014\/09\/19\/i-marked-my-parameter-as-optional-so-why-do-i-get-an-rpc-error-when-i-pass-null\/"},"modified":"2025-08-05T14:57:10","modified_gmt":"2025-08-05T21:57:10","slug":"20140919-00","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/oldnewthing\/20140919-00\/?p=44023","title":{"rendered":"I marked my parameter as [optional], so why do I get an RPC error when I pass NULL?"},"content":{"rendered":"<p>Consider the following interface declaration in an IDL file:<\/p>\n<pre><i>\/\/ Code in italics is wrong\r\n\r\ninterface IFoo : IUnknown\r\n{\r\n    HRESULT Cancel([in, optional, string] LPCWSTR pszReason);\r\n};<\/i>\r\n<\/pre>\n<p>The idea here is that you want to be able to call the <code>Cancel<\/code> method as <code>pFoo-&gt;Cancel(<wbr \/>NULL)<\/code> if you don&#8217;t want to provide a reason.<\/p>\n<p>If you try this, you&#8217;ll find that the call sometimes fails with error <tt>0x800706F4<\/tt>, which decodes to <code>HRESULT_<wbr \/>FROM_<wbr \/>WIN32(<wbr \/><a title=\"The great thing about naming conventions is that not everybody will follow them\" href=\"https:\/\/devblogs.microsoft.com\/oldnewthing\/20090828-00\/?p=16943\">RPC_<wbr \/>X_<wbr \/>NULL_<wbr \/>REF_<wbr \/>POINTER<\/a>)<\/code>. What&#8217;s going on here?<\/p>\n<p>The <code>optional<\/code> attribute does not mean what you think it means. To a C or C++ programmer, an &#8220;optional&#8221; pointer parameter typically means that it is valid to pass <code>NULL<\/code>\/<wbr \/><code>nullptr<\/code> as the parameter value. But that&#8217;s not what it means to the IDL compiler.<\/p>\n<p>To the IDL compiler, optional parameters are <a title=\"One of my favorite error codes: Optional parameter missing\" href=\"https:\/\/devblogs.microsoft.com\/oldnewthing\/20140129-00\/?p=1933\"> hints to the scripting engine that the parameter should be passed as <code>VT_<wbr \/>ERROR<\/code>\/<wbr \/><code>DISP_<wbr \/>E_<wbr \/>PARAM\u00adNOT\u00adFOUND<\/code><\/a>. The attribute is meaningful only when applied to parameters of type <code>VARIANT<\/code> or <code>VARIANT*<\/code>.<\/p>\n<p>What you actually want is the <code>unique<\/code> attribute. This somewhat confusingly-named attribute means &#8220;The parameter is allowed to be a null pointer.&#8221; Therefore, the interface should have been written as<\/p>\n<pre>interface IFoo : IUnknown\r\n{\r\n    HRESULT Cancel([in, <span style=\"border: solid 1px currentcolor;\">unique<\/span>, string] LPCWSTR pszReason);\r\n};\r\n<\/pre>\n<p>At the lowest level in the marshaler, pointer parameters are marked as <a href=\"http:\/\/msdn.microsoft.com\/library\/aa367153\"> <code>ref<\/code><\/a>, <a href=\"http:\/\/msdn.microsoft.com\/library\/aa367294\"> <code>unique<\/code><\/a>, or <a href=\"http:\/\/msdn.microsoft.com\/library\/aa367149\"> <code>ptr<\/code><\/a>. <code>ref<\/code> parameters may not be null, whereas <code>unique<\/code> and <code>ptr<\/code> parameters are allowed to be null. <a href=\"http:\/\/blogs.msdn.com\/b\/larryosterman\"> Larry Osterman<\/a> explained to me that the default for interface pointers (anything derived from <code>IUnknown<\/code>) is <code>unique<\/code> and the default for all other pointer types is <code>ref<\/code>. Therefore, if you want to say that <code>NULL<\/code> is a valid value for a non-interface pointer parameter, you must say so explicitly by annotating the parameter as <code>[unique]<\/code>.<\/p>\n<p>It&#8217;s probably too late to change the behavior of MIDL to reject the <code>[optional]<\/code> tag on non-<code>VARIANT<\/code> parameters because in the decades since the attribute was introduced, it&#8217;s probably being used incorrectly approximately twenty-five bazillion times, and making it an error would break a lot of code. (Even if you just made it a warning, that wouldn&#8217;t help because a lot of people treat warnings as errors.)<\/p>\n<p><b>Exercise<\/b>: Why is the <code>RPC_<wbr \/>X_<wbr \/>NULL_<wbr \/>REF_<wbr \/>POINTER<\/code> error raised only sometimes?<\/p>\n","protected":false},"excerpt":{"rendered":"<p>Not that kind of optional.<\/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-44023","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-oldnewthing","tag-code"],"acf":[],"blog_post_summary":"<p>Not that kind of optional.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/44023","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=44023"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/44023\/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=44023"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/categories?post=44023"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/tags?post=44023"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}