windows 8.1 _When_ How ist used ?

[TouEnMasm]

The sdk 8.1 had a new word in his header,_When_
He don't seem to generate any code ,but I don't find any information on it.
Help ?

int
WINAPI
DrawTextExW(
    _In_ HDC hdc,
    _When_((cchText) < -1, _Unreferenced_parameter_)
    _When_((format & DT_MODIFYSTRING), _Inout_grows_updates_bypassable_or_z_(cchText, 4))
    _When_((!(format & DT_MODIFYSTRING)), _At_((LPCWSTR)lpchText, _In_bypassable_reads_or_z_(cchText)))
    LPWSTR lpchText,
    _In_ int cchText,
    _Inout_ LPRECT lprc,
    _In_ UINT format,
    _In_opt_ LPDRAWTEXTPARAMS lpdtp);

[dedndave]

Code Select Expand

int DrawTextEx(
  _In_     HDC hdc,
  _Inout_  LPTSTR lpchText,
  _In_     int cchText,
  _Inout_  LPRECT lprc,
  _In_     UINT dwDTFormat,
  _In_     LPDRAWTEXTPARAMS lpDTParams
);

all the "_When_"s seem to be part of the lpchText description
notice, no argument seperating commas from first _When_ to lpchText, except those inside parens

lpchText [in, out]

    A pointer to the string that contains the text to draw. If the cchText parameter is -1, the string must be null-terminated.

    If dwDTFormat includes DT_MODIFYSTRING, the function could add up to four additional characters to this string. The buffer containing the string should be large enough to accommodate these extra characters.

so, they must be refering to the modifiers in the string   :P

Code Select Expand

_When_((format & DT_MODIFYSTRING)

[qWord]

It is an macro defined in the headers:

Code Select Expand


// _When_(expr, annos) specifies that the annotations listed in 'annos' only
// apply when 'expr' evaluates to non-zero.
#define _When_(expr, annos)  ...

[TouEnMasm]

The interesting part for me is to know if it generate code or not?.
I think not,but is it true ?.

[qWord]

These (Microsoft specific) annotations commonly evaluate to blank tokens ... however, to be sure, look up the definition.

[TouEnMasm]

Thanks seems the information below is enough
Finally found it
He don't generate code

specstring.h
/************************************************************************
*  Advanced Annotations
*
*  Advanced annotations describe behavior that is not expressible with the
*  regular buffer macros. These may be used either to annotate buffer
*  parameters that involve complex or conditional behavior, or to enrich
*  existing annotations with additional information.
*
*  _At_(expr, annotes) : annotation list annotes applies to target 'expr'
*
*  _When_(expr, annotes) : annotation list annotes applies when 'expr' is true
*
*  __success(expr) T f() : <expr> indicates whether function f succeeded or
*  not. If <expr> is true at exit, all the function's guarantees (as given
*  by other annotations) must hold. If <expr> is false at exit, the caller
*  should not expect any of the function's guarantees to hold. If not used,
*  the function must always satisfy its guarantees. Added automatically to
*  functions that indicate success in standard ways, such as by returning an
*  HRESULT.
*
*  __out_awcount(expr, size) T *p : Pointer p is a buffer whose size may be
*  given in either bytes or elements. If <expr> is true, this acts like
*  __out_bcount. If <expr> is false, this acts like __out_ecount. This
*  should only be used to annotate old APIs.
*
*  __in_awcount(expr, size) T* p : Pointer p is a buffer whose size may be given
*  in either bytes or elements. If <expr> is true, this acts like
*  __in_bcount. If <expr> is false, this acts like __in_ecount. This should
*  only be used to annotate old APIs.
*
*  __nullterminated T* p : Pointer p is a buffer that may be read or written
*  up to and including the first '\0' character or pointer. May be used on
*  typedefs, which marks valid (properly initialized) instances of that type
*  as being null-terminated.
*
*  __nullnullterminated T* p : Pointer p is a buffer that may be read or
*  written up to and including the first sequence of two '\0' characters or
*  pointers. May be used on typedefs, which marks valid instances of that
*  type as being double-null terminated.
*
*  __reserved T v : Value v must be 0/NULL, reserved for future use.
*
*  __checkReturn T f(); : Return value of f must not be ignored by callers
*  of this function.
*
*  __typefix(ctype) T v : Value v should be treated as an instance of ctype,
*  rather than its declared type when considering validity.
*
*  __override T f(); : Specify C#-style 'override' behaviour for overriding
*  virtual methods.
*
*  __callback T f(); : Function f can be used as a function pointer.
*
*  __format_string T p : Pointer p is a string that contains % markers in
*  the style of printf.
*
*  __blocksOn(resource) f(); : Function f blocks on the resource 'resource'.
*
*  __fallthrough : Annotates switch statement labels where fall-through is
*  desired, to distinguish from forgotten break statements.
*
*  __range(low_bnd, up_bnd) int f(): The return from the function "f" must
*  be in the inclusive numeric range [low_bnd, up_bnd].
*
*  __in_range(low_bnd, up_bnd) int i : Precondition that integer i must be
*  in the inclusive numeric range [low_bnd, up_bnd].
*
*  __out_range(low_bnd, up_bnd) int i : Postcondition that integer i must be
*  in the inclusive numeric range [low_bnd, up_bnd].
*
*  __deref_in_range(low_bnd, up_bnd) int* pi : Precondition that integer *pi
*  must be in the inclusive numeric range [low_bnd, up_bnd].
*
*  __deref_out_range(low_bnd, up_bnd) int* pi : Postcondition that integer
*  *pi must be in the inclusive numeric range [low_bnd, up_bnd].
*
*  __deref_inout_range(low_bnd, up_bnd) int* pi : Invariant that the integer
*  *pi must be in the inclusive numeric range [low_bnd, up_bnd].
*
*  The first argument of a range macro may also be a C relational operator
*  (<,>,!=, ==, <=, >=).
* 
*  __range(rel_op, j) int f(): Postcondition that "f() rel_op j" must be
*  true.  Note that j may be a expression known only at runtime.
*
*  __in_range(rel_op, j) int i : Precondition that "i rel_op j" must be
*  true.  Note that j may be a expression known only at runtime.
*
*  __out_range(rel_op, j) int i : Postcondition that integer "i rel_op j"
*  must be true.  Note that j may be a expression known only at runtime.
*
*  __deref_in_range(rel_op, j) int *pi : Precondition that "*pi rel_op j"
*  must be true.  Note that j may be a expression known only at runtime.
*
*  __deref_out_range(rel_op, j) int *pi : Postcondition that "*pi rel_op j"
*  must be true.  Note that j may be a expression known only at runtime.
*
*  __deref_inout_range(rel_op, j) int *pi : Invariant that "*pi rel_op j"
*  must be true.  Note that j may be a expression known only at runtime.
*
*  __range_max(a, b) int f(): Postcondition f acts as 'max', returns larger
*  of a and b.  Note that a and b may be expressions known only at runtime.
*
*  __range_min(a, b) int f(): Postcondition f acts as 'min', returns smaller
*  of a and b.  Note that a and b may be expressions known only at runtime.
*
*  __in_bound int i : Precondition that integer i must be bound, but the
*  exact range can't be specified at compile time.  __in_range should be
*  used if the range can be explicitly stated.
*
*  __out_bound int i : Postcondition that integer i must be bound, but the
*  exact range can't be specified at compile time.  __out_range should be
*  used if the range can be explicitly stated.
*
*  __deref_out_bound int pi : Postcondition that integer *pi must be bound,
*  but the exact range can't be specified at compile time.
*  __deref_out_range should be used if the range can be explicitly stated.
*
*  __assume_bound(expr); : Assume that the expression is bound to some known
*  range. This can be used to suppress integer overflow warnings on integral
*  expressions that are known to be bound due to reasons not explicit in the
*  code. Use as a statement in the body of a function.
*
*  __analysis_assume_nulltermianted(expr); : Assume that the expression is
*  a null terminated buffer. Use this to suppress tool noise specific to
*  nulltermination warnings, and capture deeper invariants tools can not
*  discover.
*
*  __allocator void f(): Function allocates memory using an integral size
*  argument
*
*  void myfree(__deallocate(Mem) void *p) : Memory is freed, no longer usable
*  upon return, and p may not be null.
*
*  void myfree(__deallocate_opt(Mem) void *p) : Memory is freed, no longer
*  usable upon return, and p may be null.
*
*  void free(__post_invalid void* x): Mark memory as untouchable when
*  function returns.
*
*  ----------------------------------------------------------------------------
*  Advanced Annotation Examples
*
*  __success(return == TRUE) LWSTDAPI_(BOOL)
*  PathCanonicalizeA(__out_ecount(MAX_PATH) LPSTR pszBuf, LPCSTR pszPath);
*  //  pszBuf is only guaranteed to be null-terminated when TRUE is returned.
*
*  // Initialized LPWSTRs are null-terminated strings.
*  typedef __nullterminated WCHAR* LPWSTR;
*
*  __out_ecount(cch) __typefix(LPWSTR) void *psz;
*  // psz is a buffer parameter which will be a null-terminated WCHAR string
*  // at exit, and which initially contains cch WCHARs.
*
************************************************************************/

[dedndave]

looks to me, as the _When_ operator(?) is part of the type definition - not the argument
you know it's a DWORD type in 32-bit (LPWSTR)
so - i would say it has little meaning in assembler, and may be parsed out (ignored)   :P