The documentation for the fCreate parameter for the SHCreateStreamOnFileEx function covers the issue, but since people seem to really like charts and tables, I'll present the same information in tabular form.
| grfMode |
fCreate |
File exists? |
Behavior |
| STGM_CREATE |
(ignored) |
Yes |
File is opened (old contents lost) |
| STGM_CREATE |
(ignored) |
No |
File is created |
| STGM_FAILIFTHERE |
FALSE |
Yes |
File is opened (old contents preserved) |
| STGM_FAILIFTHERE |
FALSE |
No |
Fails |
| STGM_FAILIFTHERE |
TRUE |
Yes |
Fails |
| STGM_FAILIFTHERE |
TRUE |
No |
File is created |
It seems somebody already put your work in the msdn library?
http://msdn2.microsoft.com/en-us/library/ms538417.aspx
Perhaps it was Raymond himself.
That table’s logic makes my head hurt. :( Especially the dual meaning of STGM_FAILIFTHERE, since it can FAILIFNOTTHERE and SUCCEEDIFTHERE if fCreate is FALSE.
The version on MSDN doesn’t say when the contents of the file are lost – seems potentially dangerous.
This reminded me of the DOS OPEN function on the Spectrum +3, where you passed a ‘create action’ saying what to do if the file didn’t exist, and an ‘open action’ saying what to do if it did. These were 0-based integers, but my copy of the manual used a 1-based list to describe them, so you had to subtract 1 from all the values it gave.
I see there’s a (corrected) online copy at http://www.worldofspectrum.org/ZXSpectrum128+3Manual/chapter8pt27.html
I’m with Dan. FAILIFTHERE fails if the file is *not* there when fCreate is FALSE, which is rather counterintuitive.
Yes, tables that cover every possibility are great! While your at it a table for VariantChangeType and/or variantchangetypeex would be great.
(Disclaimer: I added the fCreate param to SHCreateStreamOnFileEx.) The reason for the weirdness is because STGM_FAILIFTHERE is a zero flag, and we had to work within the constraints of the existing STGM enumeration.
Zero flags sometimes make sense when you’re giving a name for default behavior but this one obviously didn’t work out that well.
Isn’t that a Claimer? Doesn’t a Disclaimer mean you don’t have certain relationships to specified matters? For example when Usenet news postings used to identify which organization a writer was involved with, a disclaimer meant that that the posting wasn’t the organization’s official policy. For example, this comment wasn’t written by MSDN.
Metaclaim: Claimer wrote this metaclaim.