![[Toc]](../../toc.gif)
![[Index]](/idx.gif)
Parameter Names
Parameter names are constructed to show the data type of the parameter and
to indicate its use:
* A lowercase prefix of one or more characters that indicates the data
type.
* An optional qualifier starting with an uppercase letter.
Where possible, standard names have been used to describe
parameters. Where multiple-word qualifiers are used, the order of
the words is not significant.
For example:
hdc /* device context handle */
pszFilename /* pointer to a character string */
The following standard base tags and their associated type names are
defined:
+----------+----------+--------------------------------------------------+
|Tag |Data Type |Description |
+----------+----------+--------------------------------------------------+
|f |BOOL |Flag or Boolean variable. The qualifier describes |
| | |the condition associated with the flag when it is |
| | |TRUE. For example, fSuccess is TRUE if successful |
| | |and FALSE if not; whereas fError is TRUE if an |
| | |error occurred and FALSE if no error occurred. For|
| | |objects of type BOOL, the value 0 implies FALSE |
| | |and any nonzero value implies TRUE. |
+----------+----------+--------------------------------------------------+
|ch |CHAR |Signed eight-bit quantity; a character. |
+----------+----------+--------------------------------------------------+
|s |SHORT |Signed 16-bit quantity; a SHORT. This is often |
| | |used in place of us when it does not matter |
| | |whether the value is signed or unsigned. |
+----------+----------+--------------------------------------------------+
|l |LONG |Signed 32-bit quantity; a LONG. This is often used|
| | |in place of ul when it does not matter whether the|
| | |value is signed or unsigned. |
+----------+----------+--------------------------------------------------+
|uch |UCHAR |Unsigned eight-bit quantity; a byte. Same as b. |
+----------+----------+--------------------------------------------------+
|us |USHORT |Unsigned 16-bit quantity. |
+----------+----------+--------------------------------------------------+
|ul |ULONG |Unsigned 32-bit quantity. |
+----------+----------+--------------------------------------------------+
|b |BYTE |Unsigned eight-bit quantity; a byte. Same as uch. |
+----------+----------+--------------------------------------------------+
|sz |CHAR[ ] |NULL-terminated string of characters. |
+----------+----------+--------------------------------------------------+
|fb |UCHAR |Byte of flags, that is, an array of flags packed |
| | |in a BYTE. |
+----------+----------+--------------------------------------------------+
|fs |USHORT |SHORT of flags, that is, an array of flags packed |
| | |in a USHORT. |
+----------+----------+--------------------------------------------------+
|fl |ULONG |LONG of flags, that is, an array of flags packed |
| | |in a ULONG. The three preceding types are used |
| | |when more than one flag is combined into a byte, |
| | |SHORT or LONG. Typically, the values are combined |
| | |with the OR operator and are always unsigned. |
+----------+----------+--------------------------------------------------+
|r |REAL |Real number, single precision 32-bits. |
+----------+----------+--------------------------------------------------+
|rd |DOUBLE |Real number, double precision 64-bits. |
+----------+----------+--------------------------------------------------+
|pfn | |Pointer to a function. |
+----------+----------+--------------------------------------------------+
|x | |X-coordinate. |
+----------+----------+--------------------------------------------------+
|y | |Y-coordinate. |
+----------+----------+--------------------------------------------------+
The following standard prefixes are also defined:
+----------+--------------------------------------------------+
|Prefix |Description |
+----------+--------------------------------------------------+
|p |32-bit pointer for an 80386 microprocessor. For |
| |example, pch is a pointer to a character. |
+----------+--------------------------------------------------+
|a |Array. For example, ach is an array of characters.|
+----------+--------------------------------------------------+
|i |Index to an array. For example, an ich is used to |
| |index an ach. |
+----------+--------------------------------------------------+
|c |Count. For example, cch is a count of characters. |
+----------+--------------------------------------------------+
|d |Delta or difference between instances of a type. |
| |For example, dx is the difference between two |
| |values of x. |
+----------+--------------------------------------------------+
|h |Handle. A value that uniquely identifies an object|
| |but cannot directly be used to access it. For |
| |example, hps is a PS handle. |
+----------+--------------------------------------------------+
|mp |Mapping array. This prefix is always followed by |
| |two base types rather than one and represents the |
| |most general case of an array. Mathematically, an |
| |array is a function mapping the index to the value|
| |stored in the array. The prefix mp is an |
| |abbreviation of map. In the construct mpab, a is |
| |the type of the index and b is the type of the |
| |value stored in the array. In most cases, the only|
| |type that is important is the type of the value. |
| |The index is usually an integer with no other |
| |meaning (the a prefix is used in this instance). |
+----------+--------------------------------------------------+
|off |Offset. Generally used as an offset within a data |
| |structure. The actual address of the element |
| |within the data structure is derived by adding an |
| |offset to a pointer, which points to the beginning|
| |of the data structure. Normally, OFF is a byte |
| |offset. For example: pfoo = (FOO *)((BYTE |
| |*)pfooBase + 0fff00) |
+----------+--------------------------------------------------+
|id |Identifier. This is generally used for values that|
| |identify some object. Usually the association of |
| |the ID value and the object are established by the|
| |programmer. For example, all windows are |
| |identified by their Window ID, which can be set |
| |and queried by the programmer. |
+----------+--------------------------------------------------+
|cmd |Command. Used for command values, typically as |
| |function parameters. |
+----------+--------------------------------------------------+
Some parameters are used in pairs; the qualifiers that are used reflect
the relationship between the two variables. For example:
+------------+-------------------------------------------------------------------+
|Parameter |Description |
+------------+-------------------------------------------------------------------+
|First/Last |First and last elements in a set. These are typically used with |
| |indexes or pointers (pchFirst, pchLast). Both values represent |
| |valid values (compare with Min/Max below). For all valid values of |
| |x: xFirst <= x <= xLast. The use of > with First or < with Last is |
| |almost always an "off-by-one" error. |
| |For example, to determine whether an ich is within ichFirst and |
| |ichLast: if (ich >= ichFirst && ich <= ichLast) |
| | ... |
| |A typical loop: |
| | for (ich = ichFirst; ich <= ichLast; ich++) |
| | ... |
+------------+-------------------------------------------------------------------+
|Min/Max |Similar to First/Last except that Max is not a valid value in the |
| |set (Min is a valid value). For all valid values of x in the set: |
| |xMin < = x < xMax. The use of > with Min or < = with Max is almost |
| |always an "off-by-one" error. |
| |For example, to determine whether an ich is within ichMin and |
| |ichMax: if (ich >= ichMin && ich < ichMax) |
| | ... |
| |A typical loop: |
| | for (ich = ichMin; ich < /* or != */ ichMax; ich++) |
| | ... |
+------------+-------------------------------------------------------------------+
| |The current value (Cur) qualifier can be used with Min and Max when|
| |Min or Max can change over time (for example, pbStackMaxCur). |
+------------+-------------------------------------------------------------------+
|Old/New |Old and new. Typically used for values or states when it is |
| |necessary to compare the old and new states of the value. |
+------------+-------------------------------------------------------------------+
|Next/Prev |Next and previous. Typically used in situations in which items are |
| |being enumerated, such as with linked lists. |
+------------+-------------------------------------------------------------------+
|Src/Dst |Source and destination. Typically used in transfer operations. |
+------------+-------------------------------------------------------------------+
|T |A temporary value. |
+------------+-------------------------------------------------------------------+
|Save |A temporary, saved value. Typically used when saving and restoring |
| |some state. |
+------------+-------------------------------------------------------------------+
|Cur |Current value. |
+------------+-------------------------------------------------------------------+
The base types and their prefixes are defined as follows:
+------------------------+----------------------+
|Data Type |Prefix |
+------------------------+----------------------+
|PSZ |psz |
+------------------------+----------------------+
|PCH |pch |
+------------------------+----------------------+
|HAB |hab |
+------------------------+----------------------+
|HPS |hps |
+------------------------+----------------------+
|HDC |hdc |
+------------------------+----------------------+
|HRGN |hrgn |
+------------------------+----------------------+
|HBITMAP |hbmp |
+------------------------+----------------------+
|PLONG |pl |
+------------------------+----------------------+
|POINTL |ptl |
+------------------------+----------------------+
|POINTL |pt |
+------------------------+----------------------+
|RECTL |rcl |
+------------------------+----------------------+
|RECTL |rc |
+------------------------+----------------------+
|HWND |hwnd |
+------------------------+----------------------+
|WPOINT |wpt |
+------------------------+----------------------+
|WRECT |wrc |
+------------------------+----------------------+
|FIXED |fx |
+------------------------+----------------------+
Parameters for defined structures are the defined parameter names. For
example:
--------------------------------------------------------------
AREADEFS struct
{
defSet
fFlags
CodePage
}AREADEFS
--------------------------------------------------------------
System-defined constants and flags are represented as two or more
uppercase WORDs or mnemonic abbreviations separated by underscores. For
example, SYS_CONSTANT and SYS_FLAG.
Created using Inf-PHP v.2 (c) 2003 Yuri Prokushev
Created using Inf-HTML v.0.9b (c) 1995 Peter Childs