## String Functions

The Wxutil.h header file in the DirectShow base classes provides wide string functions, if they are not already provided by the Microsoft® Win32® environment.

Function | Description
AMGetWideString | Allocates and creates a wide string version of an existing nonwide string.
lstrcmpiW | Compares two wide strings, ignoring case.
lstrcmpW | Compares two wide strings.
lstrcpynW | Copies one wide string to another, with a maximum length.
lstrcpyW | Copies one wide string to another.
lstrlenW | Gets the length of a wide string in wide characters.

###

AMGetWideString

String Functions

Allocates and creates a Unicode version of an existing non-Unicode string.

STDAPI AMGetWideString(
LPCWSTR pszString,
LPWSTR *ppszReturn
);

##### Parameters

pszString
  Non-Unicode source string.
ppszReturn
  Address of a Unicode string that will contain pszString.

##### Return Values

Returns S_OK if successful, E_POINTER if ppszReturn is NULL, or E_OUTOFMEMORY if not enough memory is available.

###

lstrcmpiW

String Functions

Compares two wide-character strings. The comparison is not case sensitive.

int lstrcmpiW(
LPCWSTR lpszString1,
LPCWSTR lpszString2
);

##### Parameters

lpszString1
  Pointer to the first null-terminated wide string to be compared.
lpszString2
  Pointer to the second null-terminated wide string to be compared.

##### Return Values

Returns a negative value if the function succeeds and the string that lpszString1 points to is less than the string that lpszString2 points to. Returns a positive value if the string that lpszString1 points to is greater than the string that lpszString2 points to. Returns zero if the strings are equal.

##### Remarks

The lstrcmpiW function compares two wide strings by checking the first characters against each other, the second characters against each other, and so on until it finds an inequality or reaches the ends of the strings.

The function returns the difference of the values of the first unequal characters it encounters. For instance, lstrcmpiW determines that L"abcz" is greater than L"abcdefg" and returns the difference of L'z' and L'd'.

The language (locale) is treated as always being English.

###

lstrcmpW

String Functions

Compares two wide-character strings. The comparison is case sensitive.

int lstrcmpW(
LPCWSTR lpszString1,
LPCWSTR lpszString2
);

##### Parameters

lpszString1
  Pointer to the first null-terminated wide string to be compared.
lpszString2
  Pointer to the second null-terminated wide string to be compared.

##### Return Values

Returns a negative value if the function succeeds and the string that lpszString1 points to is less than the string that lpszString2 points to. Returns a positive value if the string that lpszString1 points to is greater than the string that lpszString2 points to. Returns zero if the strings are equal.

##### Remarks

The lstrcmpW function compares two wide strings by checking the first characters against each other, the second characters against each other, and so on until it finds an inequality or reaches the ends of the strings.

The function returns the difference of the values of the first unequal characters it encounters. For instance, lstrcmpW determines that L"abcz" is greater than L"abcdefg" and returns the difference of L'z' and L'd'.

The language (locale) is treated as always being English.

###

lstrcpyW

String Functions

Copies a wide string to a buffer.

LPWSTR lstrcpyW(
LPWSTR lpszString1,
LPCWSTR lpszString2
);

##### Parameters

lpszString1
  Pointer to a buffer to receive the contents of the string pointed to by the lpszString2 parameter. The buffer must be large enough to contain the string, including the terminating wide null character.
lpszString2
  Pointer to the null-terminated wide string to be copied.

##### Return Values

Returns a pointer to the buffer.

###

lstrcpynW

String Functions

Copies a wide string to a buffer, up to a specified number of wide characters.

LPWSTR lstrcpynW(
LPWSTR lpszString1,
LPCWSTR lpszString2,
int iMaxLength
);

##### Parameters

lpszString1
  Pointer to a buffer to receive the contents of the string that the lpszString2 parameter points to. The buffer must be large enough to contain the string, including the terminating wide null character.
lpszString2
  Pointer to the null-terminated wide string to be copied.
iMaxLength
  Maximum number of wide characters to copy, including a terminating null character.

##### Return Values

Returns a pointer to the buffer.

##### Remarks

If iMaxLength is nonzero, lstrcpynW always inserts a terminating null wide character in the destination string, which could result in the source string being truncated.

###

lstrlenW

String Functions

Retrieves the length of the specified wide string.

int lstrlenW(
LPCWSTR lpszString
);

##### Parameters

lpszString
  Pointer to a null-terminated wide string.

##### Return Values

If the function succeeds, the return value specifies the length of the string, in wide characters.

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.