If you don’t want the changes to be permanent, the don’t pass the flag that says that you want the changes to be permanent

A customer wanted to make a change to a system setting. We advised them to use the System­Parameters­Info function, adding

The System­Parameters­Info function lets you specify whether you want the change to be permanent or this-session-only.

The customer wrote back,

Were trying to figure out whether there is a way for the settings to only apply for the current user session (e.g. automatically restore itself on the next reboot). Your engineers alluded earlier that this is possible, though looking at the MSDN docs on SetParametersInfo, it seems that both options persist the setting permanently:

Writes the new system-wide parameter setting to the user profile.
Broadcasts the WM_SETTING­CHANGE message after updating the user profile.

What are we missing?

These two flags control different things. The SPIF_SEND­CHANGE message controls whether the WM_SETTING­CHANGE message is sent to all top-level windows to inform them of the change. It has nothing to do with whether the change is temporary or permanent.

The first flag is the relevant one here. If you pass the SPIF_UPDATE­INI­FILE flag, then the changes are written to the user profile, so that they also take effect the next time the user logs on.

Since this customer doesn't want the changes to persist beyond the current session, what they want to do is omit the SPIF_UPDATE­INI­FILE flag. Maybe it never occurred to them that they can omit flags.

The customer clarified:

We were wondering if someone could give me more insight into how to accomplish this. We were looking into the System­Parameters­Info MSDN page, specifically at the "UINT fWinIni" parameter. We are not sure what is meant by the update the user profile. Does this mean these settings persist longer than the current user session?

Let me see if I can explain this in simpler terms.

If you pass the SPIF_UPDATE­INI­FILE flag, then the change is written to the user profile. This means that the setting takes effect not only right away but also the next time the user logs on. If you do not pass the SPIF_UPDATE­INI­FILE flag, then the setting takes effect right away, but it does not affect what happens the next time the user logs on.

Comments (21)
  1. Vilx- says:

    Consider yourself lucky. This customer at least is trying to READ the documentation. We have a customer that has at least 3(!) developers who don’t bother doing even that. For any question that they have, they just straight away ask our customer support. Never mind that the answer is clearly stated in the documentation and easy to find.

    1. Kirby FC says:

      “Never mind that the answer is clearly stated in the documentation and easy to find.”

      If you know what to look for, it seems easy and obvious. Yes, there are people who don’t even try to find the answer. However, I have had occasions where I couldn’t find the answer because I didn’t know what to look for, or, was using the wrong words in my search.

      1. jimbo1qaz says:

        If people frequently use a specific keyword not included in the documentation, then the documentation should be updated to add the keyword, to help searchability.

        I have this complaint about manpages (something about curl, -O automatic file name, or find) as well.

  2. Karellen says:

    Ah yes. The junior developer who has plenty of exposure to enumerated sets, but little experience of bitwise flags (or bitwise anything), and expects there to be a named constant for all possible values, including ‘0’. (e.g. SPIF_SESSIONONLY).

    Warning – these developers sometimes add the flags instead of or-ing them. This seems to work fine… until the day that they pass a flag twice and things get very confusing.

    1. parkrrrr says:

      Or they pass WS_OVERLAPPEDWINDOW+WS_CAPTION or similar. (Which is also passing the flag twice, but less obviously so.)

    2. ranta says:

      Rarely, adding the flag is right. MSIDBOPEN_READONLY | MSIDBOPEN_PATCHFILE won’t even compile; you have to use MSIDBOPEN_READONLY + MSIDBOPEN_PATCHFILE.

  3. Mike Caron says:

    But, what do I do if I don’t want the changes persisted for the user?

  4. Ray Koopa says:

    At least they also didn’t know how to omit reading documentation, and had a try.

  5. alv says:

    Maybe the source confusion is that they want to broadcast the WM_SETTINGCHANGE message, but don’t want to permanently update the user’s profile. “Broadcasts the WM_SETTING­CHANGE message after updating the user profile” indicates that it does both.

  6. Mr Cranky says:

    “What are we missing?”
    So many possibilities, so little time.
    a) Comprehension.
    b) Common sense.
    c) Brain.

    1. xcomcmdr says:

      And you lack humility. Perfect !

  7. jon says:

    To be fair, you have to have some experience reading Microsoft documentation to know that “after updating the user profile” doesn’t actually mean you HAVE to update the user profile.

  8. Dave Bacher says:

    Adding an alias for the flag might be a good idea in this case.

    Create a new semantic flag with the same value as the existing flag.
    #define the existing flag to the new semantic flag’s name.
    Reference the old flag’s name from the documentation with “SPIF_UPDATEINIFILE is a legacy flag.”

    What I’m about to say is going to make some people feel very old…

    But it’s been a very long time since WriteProfileString was the primary mechanism for saving data. It’s even been a long time since WritePrivateProfileString was. It’s been over 20 years for WritePrivateProfileString. For the past decade, the move has been to JSON or XML, and for the decade before that the move was to the Windows registry.

    Just saying, there is an entire generation of developers who have never had to deal with win.ini or WritePrivateProfileString. The flag was communicative when it was named, but for that entire generation — it is just random letters chained together.

  9. blorgbeard says:

    In normal English, “Do X after doing Y” implies both X and Y will occur.

    This is a documentation bug, and nothing to do with the number of syllables involved.

    1. They didn’t want either thing to happen. The deal is that they didn’t realize it was possible to omit BOTH flags.

      1. SimonRev says:

        In fairness, I have been working with Win32 docs for over 20 years and I can say that even today it still takes a few extra mental cycles to remember that I can pass zero into a flags field after reviewing all available flags and deciding I don’t want any of them. For me, at least, it isn’t intuitive to pass zero into an enumerated field like that, even though I am perfectly aware that I can.

  10. Phlip says:

    Sounds like they saw the list of options, and thought it was an enum, rather than a bitset…

    I note that the documentation now says:
    “This parameter can be zero if you do not want to update the user profile or broadcast the WM_SETTINGCHANGE message, or it can be one or more of the following values.”

    I wonder if that sentence was there when this story happened, or if it had been added since…

    1. Erik F says:

      I was thinking along the same lines. Although this function allows for no flags to be set, there are other functions that require exactly one setting, or at least one setting. The documentation does not always make this distinction clear, unfortunately. Having a flag called SPIF_NOUPDATEINIFILE would make this clearer. Changing INIFILE to USERPROFILE would be nice too, but that’s a nitpicky issue.

      For this function, if I was reading the documentation for the first time I could easily think that SPIF_SENDCHANGE is dependent on SPIF_UPDATEINIFILE being set (wouldn’t an update to the user profile be a write by necessity?) The conflation of temporary user profile settings (“session user profile” perhaps?) with the on-disk user profile makes this one interesting.

  11. Matteo Italia says:

    This kind of exchange looks all too familiar to anyone who visits StackOverflow often enough – including the spelling of “were trying” and the “Let me see if I can explain this in words of no more than three syllables.” finale.

    Raymond you probably need some kind of internal-use downvote button for customer questions, even just for psychological relief.

  12. sh_code says:

    To be fair, the docs are not worded well. Both flags talk about “propagating changes into user profile”, which even to me sounds like “both flags save the changes, but in a different way

  13. I would suggest they define a new flag
    #define TEMPORARY_CHANGE 0
    and then tell them use that flag.

Comments are closed.

Skip to main content