msdn随手笔记(五) --size_is;_strnicmp...;GetCommandLine;reinterpret_cast;ATL and MFC String Conversion Macros

Use the [size_is] attribute to specify the size of memory allocated for sized pointers, sized pointers to sized pointers, and single- or multidimensional arrays.

[ size_is(limited-expression-list) ]

Parameters

limited-expression-list

Specifies one or more C-language expressions. Each expression evaluates to a non-negative integer that represents the amount of memory allocated to a sized pointer or an array. In the case of an array, specifies a single expression that represents the allocation size, in elements, of the first dimension of that array. The MIDL compiler supports conditional expressions, logical expressions, relational expressions, and arithmetic expressions. MIDL does not allow function invocations in expressions and does not allow increment and decrement operators. Use commas as placeholders for implicit parameters, or to separate multiple expressions.

Return Values

This control code"s function has no return values.

Remarks

If you are using the [size_is] attribute to allocate memory for a multidimensional array and you are using array [ ] notation, keep in mind that only the first dimension of a multidimensional array can be dynamically determined at run time. The other dimensions must be statically specified. For more information on using the [size_is] attribute with multiple levels of pointers to enable a server to return a dynamically-sized array of data to a client, as shown in the example Proc7, see Multiple Levels of Pointers.

You can use either [size_is] or [max_is] (but not both in the same attribute list) to specify the size of an array whose upper bounds are determined at run time. Note, however, that the [size_is] attribute cannot be used on array dimensions that are fixed. The [max_is] attribute specifies the maximum valid array index. As a result, specifying [size_is(n)] is equivalent to specifying [max_is(n-1)].

An [in] or [in, out] conformant-array parameter with the [string] attribute need not have the [size_is] or [max_is] attribute. In this case, the size of the allocation is determined from the NULL terminator of the input string. All other conformant arrays with the [string] attribute must have a [size_is] or [max_is] attribute.

While it is legal to use the [size_is] attribute with a constant, doing so is inefficient and unnecessary. For example, use a fixed size array:

HRESULT Proc3([in] short Arr[MAX_SIZE]);

instead of:

// legal but marshaling code is much slower
HRESULT Proc3([in size_is(MAX_SIZE)] short Arr[] );

You can use the [size_is] and [length_is] attributes together. When you do, the [size_is] attribute controls the amount of memory allocated for the data. The [length_is] attribute specifies how many elements are transmitted. The amount of memory specified by the [size_is] and [length_is] attributes need not be the same. For instance, your client may pass an [in,out] parameter to a server and specify a large memory allocation with [size_is], even though it specifies a small number of data elements to be passed with [length_is]. This enables the server to fill the array with more data than it received, which it can then send back to the client.

In general, it isn"t useful to specify both [size_is] and [length_is] on [in] or [out] parameters. In both cases, [size_is] controls memory allocation. Your application could use [size_is] to allocate more array elements than it transmits (as specified by [length_is]). However, this would be inefficient. It would also be inefficient to specify identical values for [size_is] and [length_is]. It would create extra overhead during parameter marshaling. If the values of [size_is] and [length_is] are always the same, omit the [length_is] attribute.

Example Code

HRESULT Proc1(
    [in] short m;
    [in, size_is(m)] short a[]);  // If m = 10, a[10]
HRESULT Proc2(
    [in] short m;
    [in, size_is(m)] short b[][20]);  // If m = 10, b[10][20]
HRESULT Proc3(
    [in] short m;
    [size_is(m)] short * pshort); /* Specifies a pointer
                                  to an m-sized block of shorts */
HRESULT Proc4(
    [in] short m;
    [size_is( , m)] short ** ppshort); /* Specifies a pointer 
                                       to a pointer to an m-sized 
                                       block of shorts */
HRESULT Proc5(
    [in] short m;
    [size_is(m ,)] short ** ppshort); /* Specifies an
                                      m-sized block of pointers 
                                      to shorts */
HRESULT Proc6(
    [in] short m;
    [in] short n;
    [size_is(m,n)] short ** ppshort); /* Specifies a pointer to an 
                                      m-sized block of pointers, each 
                                      of which points to an n-sized 
                                      block of shorts.*/
 HRESULT Proc7(
     [out] long  * pSize,
     [out, size_is( , *pSize)] my_type ** ppMyType); /* Specifies a pointer 
                                              to a sized pointer, 
                                              which points to a block 
                                              of my_types, whose size is
                                              unknown when the stub 
                                              calls the server. */

See Also

arrays, Field Attributes, first_is, Interface Definition (IDL) File, in, last_is, length_is, max_is, min_is, out, string

Compare characters of two strings without regard to case.

int _strnicmp(
   const char *string1,
   const char *string2,
   size_t count 
);
int _wcsnicmp(
   const wchar_t *string1,
   const wchar_t *string2,
   size_t count 
);
int _mbsnicmp(
   const unsigned char *string1,
   const unsigned char *string2,
   size_t count 
);

Parameters

string1, string2

Null-terminated strings to compare.

count

Number of characters to compare.

Return Value

Indicates the relationship between the substrings as follows.

Return value	Description
< 0	string1 substring less than string2 substring
0	string1 substring identical to string2 substring
> 0	string1 substring greater than string2 substring

On an error, _mbsnicmp returns _NLSCMPERROR, which is defined in STRING.H and MBSTRING.H.

Remarks

The _strnicmp function lexicographically compares, at most, the first count characters of string1 and string2. The comparison is performed without regard to case; _strnicmp is a case-insensitive version of strncmp. The comparison ends if a terminating null character is reached in either string before count characters are compared. If the strings are equal when a terminating null character is reached in either string before count characters are compared, the shorter string is lesser.

Two strings containing characters located between "Z" and "a" in the ASCII table ("[", "/", "]", "^", "_", and "`") compare differently, depending on their case. For example, the two strings "ABCDE" and "ABCD^" compare one way if the comparison is lowercase ("abcde" > "abcd^") and the other way ("ABCDE" < "ABCD^") if it is uppercase.

_wcsnicmp and _mbsnicmp are wide-character and multibyte-character versions of _strnicmp. The arguments and return value of _wcsnicmp are wide-character strings; those of _mbsnicmp are multibyte-character strings. _mbsnicmp recognizes multibyte-character sequences according to the current multibyte code page and returns _NLSCMPERROR on an error. For more information, see Code Pages. These three functions behave identically otherwise. These functions are affected by the current locale setting.

> 0	string1 substring greater than string2 substring

On an error, _mbsnicmp returns _NLSCMPERROR, which is defined in STRING.H and MBSTRING.H.

Remarks

The _strnicmp function lexicographically compares, at most, the first count characters of string1 and string2. The comparison is performed without regard to case; _strnicmp is a case-insensitive version of strncmp. The comparison ends if a terminating null character is reached in either string before count characters are compared. If the strings are equal when a terminating null character is reached in either string before count characters are compared, the shorter string is lesser.

Two strings containing characters located between "Z" and "a" in the ASCII table ("[", "/", "]", "^", "_", and "`") compare differently, depending on their case. For example, the two strings "ABCDE" and "ABCD^" compare one way if the comparison is lowercase ("abcde" > "abcd^") and the other way ("ABCDE" < "ABCD^") if it is uppercase.

_wcsnicmp and _mbsnicmp are wide-character and multibyte-character versions of _strnicmp. The arguments and return value of _wcsnicmp are wide-character strings; those of _mbsnicmp are multibyte-character strings. _mbsnicmp recognizes multibyte-character sequences according to the current multibyte code page and returns _NLSCMPERROR on an error. For more information, see Code Pages. These three functions behave identically otherwise. These functions are affected by the current locale setting.

Requirements

Routine	Required header	Compatibility
_strnicmp	<string.h>	Win 98, Win Me, Win NT, Win 2000, Win XP
_wcsnicmp	<string.h> or <wchar.h>	Win 98, Win Me, Win NT, Win 2000, Win XP
_mbsnicmp	<mbstring.h>	Win 98, Win Me, Win NT, Win 2000, Win XP

The GetCommandLine function retrieves the command-line string for the current process.

LPTSTR GetCommandLine(void);

Parameters

This function has no parameters.

Return Values

The return value is a pointer to the command-line string for the current process.

Remarks

ANSI console processes written in C can use the argc and argv arguments of the main function to access the command-line arguments. ANSI GUI applications can use the lpCmdLine parameter of the WinMain function to access the command-line string, excluding the program name. The reason that main and WinMain cannot return Unicode strings is that argc, argv, and lpCmdLine use the LPSTR data type for parameters, not the LPTSTR data type. The GetCommandLine function can be used to access Unicode strings, because it uses the LPTSTR data type.

To convert the command line to an argv style array of strings, call the CommandLineToArgvW function.

Note  The name of the executable in the command line that the operating system provides to a process is not necessarily identical to that in the command line that the calling process gives to the CreateProcess function. The operating system may prepend a fully qualified path to an executable name that is provided without a fully qualified path.

Requirements

Client: Requires Windows XP, Windows 2000 Professional, Windows NT Workstation, Windows Me, Windows 98, or Windows 95.
Server: Requires Windows Server 2003, Windows 2000 Server, or Windows NT Server.
Unicode: Implemented as Unicode and ANSI versions on all platforms.
Header: Declared in Winbase.h; include Windows.h.
Library: Use Kernel32.lib.

See Also

CommandLineToArgvW, CreateProcess, Processes and Threads Overview, Process and Thread Functions

reinterpret_cast < type-id > ( expression )

The reinterpret_cast operator allows any pointer to be converted into any other pointer type. It also allows any integral type to be converted into any pointer type and vice versa. Misuse of the reinterpret_cast operator can easily be unsafe. Unless the desired conversion is inherently low-level, you should use one of the other cast operators.

The reinterpret_cast operator can be used for conversions such as char* to int*, or One_class* to Unrelated_class*, which are inherently unsafe.

The result of a reinterpret_cast cannot safely be used for anything other than being cast back to its original type. Other uses are, at best, nonportable.

The reinterpret_cast operator cannot cast away the const, volatile, or __unaligned attributes. See const_cast Operator for information on removing these attributes.

The reinterpret_cast operator converts a null pointer value to the null pointer value of the destination type.

One practical use of reinterpret_cast is in a hash function, which maps a value to an index in such a way that two distinct values rarely end up with the same index.

#include <iostream.h>

unsigned short Hash( void *p )
// Returns a hash code based on an address
{
  unsigned int val = reinterpret_cast<unsigned int>( p );
  return ( unsigned short )( val ^ (val >> 16));
}

void main()
{
  int a[20];
  for ( int i = 0; i < 20; i++ )
    cout << Hash( a + i ) << endl;
}

The reinterpret_cast allows the pointer to be treated as an integral type. The result is then bit-shifted and XORed with itself to produce a unique index (unique to a high degree of probability). The index is then truncated by a standard C-style cast to the return type of the function.

ATL 3.0 String Conversion Macros

The original text conversion macros are still available and are listed in the table below:

ATL 3.0 String Conversion Macros

A2BSTR	OLE2A	T2A	W2A
A2COLE	OLE2BSTR	T2BSTR	W2BSTR
A2CT	OLE2CA	T2CA	W2CA
A2CW	OLE2CT	T2COLE	W2COLE
A2OLE	OLE2CW	T2CW	W2CT
A2T	OLE2T	T2OLE	W2OLE
A2W	OLE2W	T2W	W2T

The syntax for using these macros is as follows:

For example:

In the macro names, the source string type is on the left (for example, A) and the destination string type is on the right (for example, W). A stands for LPSTR, OLE stands for LPOLESTR, T stands for LPTSTR, and W stands for LPWSTR.

If there is a C in the macro name, the macro converts to a const string. For example, W2CA converts an LPWSTR to an LPCSTR.

Thus, A2W converts an LPSTR to an LPWSTR, OLE2T converts an LPOLESTR to an LPTSTR, and so on.

The behavior of the ATL string conversion macros depends on the compiler directive in effect, if any. If the source and destination types are the same, no conversion takes place. Compiler directives change T and OLE as follows:

Compiler directive in effect	T becomes	OLE becomes
none	A	W
_UNICODE	W	W
OLE2ANSI	A	A
_UNICODE and OLE2ANSI	W	A

The destination string is created using _alloca, except when the destination type is BSTR. Using _alloca allocates memory off the stack, so that when your function returns, it is automatically cleaned up. By default this macro will only convert up to 500KB at one time.

When using an ATL string conversion macro, specify the USES_CONVERSION macro at the beginning of your function in order to avoid compiler errors. For example:

void func( LPSTR lpsz )
{
   USES_CONVERSION;
   ...
   LPWSTR x = A2W(lpsz)
   // Do something with x
   ...
}