msdn学习笔记(三):htons;size_is;

1.htons

The htons function converts a u_short from host to TCP/IP network byte order (which is big-endian).

u_short htons(
  u_short hostshort
);

Parameters

hostshort

[in] 16-bit number in host byte order.

Return Values

The htons function returns the value in TCP/IP network byte order.

Remarks

The htons function takes a 16-bit number in host byte order and returns a 16-bit number in network byte order used in TCP/IP networks.

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.
Header: Declared in Winsock2.h.
Library: Use Ws2_32.lib.

2.size_is

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 tabindex="0" keywords="_rpc_multiple_levels_of_pointers" errorurl="../common/badjump.htm"/>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, tabindex="0" keywords="rpc.field_attributes" errorurl="../common/badjump.htm"/>Field Attributes, first_is, Interface Definition (IDL) File, in, last_is, length_is, max_is, min_is, out, string