"If the function fails, the return value is NULL"

[jj2007]

If the docs say a function returns NULL on failure, then NULL will be returned only in the event of failure, otherwise you can expect a legitimate usable value.

Tedd,

I am afraid it is not that simple.
MSDN:

If the function succeeds, the return value is the requested ... setting.
If the function fails, the return value is 0. GetLastError does not provide extended error information.

Wow...! This is probably the worst case, but it's a real case. I tested this function on my puter, and got zero returned for more than a quarter of the requested settings. You all know the function - test yourself :green

include \masm32\MasmBasic\MasmBasic.inc   ; download
; ####### Create a list with the SM_xxx codes of GetSystemMetrics ##########
  Init
  Let esi=FileRead$("sysinfo.txt")   ; any file with copy & pasted stuff containing the SM_ codes
  Let edi="SysMetrics.lst"   ; the file with codes ready for use with a psm macro
  Open "O", #1, edi
  void Instr_(esi, "SM_")   ; set a seed for repeated Instr
  .Repeat
     lea ecx, [eax+3]   ; isolate the SM_x element
     .Repeat
          inc ecx
     .Until byte ptr [ecx]<"0"   ; SM_...
     sub ecx, eax
     PrintLine #1, "psm ", Left$(eax, ecx)
  .Until !Instr_(0, esi, "SM_")
  Close
  Recall edi, L$()   ; get the file as a string array
  push eax
  QSort L$()      ; we want a sorted list
  Open "O", #1, edi
  mov esi, L$(0)   ; seed string for duplicates test
  pop eax
  For_ ebx=0 To eax
     .if StringsDiffer(esi, L$(ebx))   ; avoid duplicates
          PrintLine #1, esi
          mov esi, L$(ebx)
     .endif
  Next
  Close
  Inkey "Copy to clipboard (c) or launch notepad (n)?", CrLf$
  .if eax=="n"
       Launch Cat$("Notepad.exe "+edi)
  .elseif eax=="c"
       SetClip$ Cat$(FileRead$(edi))
       PrintLine "SM list on clipboard"
  .endif
  Inkey "ok"
  Exit
end start

Full example attached. For the lazy ones: MySystemMetrics.exe generates results for your puter. Very useful for software development on different machines, by the way :bg

[Tedd]

I am afraid it is not that simple.
MSDN:

If the function succeeds, the return value is the requested ... setting.
If the function fails, the return value is 0. GetLastError does not provide extended error information.

Wow...! This is probably the worst case, but it's a real case. I tested this function on my puter, and got zero returned for more than a quarter of the requested settings.

I'll be accused of being picky here, but there is an important distinction -- NULL and zero are not the same.
NULL equates to zero, but the meaning is different. Zero means a numeric value of zero, NULL means a pointer with no value (the binary value for which happens to be 0 so it's easy to check.)

So, if the docs say NULL (not zero) is returned on failure, then NULL is an otherwise invalid value and should not be returned in any other case. Whereas if the docs say zero is returned on failure, then it may also be the case that zero could be a valid return value in the case of success - in this case there should be some other indication of failure (to double-check.)
Obviously GetSystemMetrics distorts all of this, but I suspect the only failure case for this function is passing in an invalid SM_ code and then zero is returned as a default; in all other cases the function succeeds and zero is a valid return value. But setting LastError would have been thoughtful. :lol

[dedndave]

i think GetSystemMetrics returns 0 if the requested index is unsupported, as well
since there is no indication of function failure, it might be interpreted as an ambiguity

[qWord]

The question is, why GetSystemMetrics should fail. The only reason I can think of, is that the current OS doesn't support requested property. But this should not be a problem, because it is documented which version are not supported.

[jj2007]

I'll be accused of being picky here, but ... NULL means a pointer

I might be accused of being picky here, but ... NULL is not necessarily a pointer :green
(besides, the distinction between 0 and zero and NULL is pretty academic - try handling it programmatically in assembler ::))