What does the fCreate parameter to SHCreateStreamOnFileEx mean?


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
Comments (9)
  1. ac says:

    It seems somebody already put your work in the msdn library?

    http://msdn2.microsoft.com/en-us/library/ms538417.aspx

  2. Henrik says:

    Perhaps it was Raymond himself.

  3. Dan says:

    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.

  4. jj says:

    The version on MSDN doesn’t say when the contents of the file are lost – seems potentially dangerous.

    [It is already documented that STGM_CREATE deletes the old storage if it existed. -Raymond]
  5. John Elliott says:

    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

  6. Miral says:

    I’m with Dan.  FAILIFTHERE fails if the file is *not* there when fCreate is FALSE, which is rather counterintuitive.

  7. Jim Kane says:

    Yes, tables that cover every possibility are great!  While your at it a table for VariantChangeType and/or variantchangetypeex would be great.

  8. Tyler Beam says:

    (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.

  9. Claimer says:

    (Disclaimer: I added the fCreate param to

    SHCreateStreamOnFileEx.)

    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.

Comments are closed.

Skip to main content