String Functions

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

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 Retrieves the length of a wide string in wide characters.

AMGetWideString

String Functions

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

Syntax

STDAPI AMGetWideString(
    LPCWSTR pszString,
    LPWSTR *ppszReturn
    );

Parameters

pszString
Pointer to a non-Unicode source string.
ppszReturn
Address of a pointer to a Unicode string that will contain pszString.

Return Value

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.

Syntax

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 Value

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.

Syntax

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 Value

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.

Syntax

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 Value

Returns a pointer to the buffer.

lstrcpynW

String Functions

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

Syntax

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 Value

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.

Syntax

int lstrlenW(
    LPCWSTR lpszString
    );

Parameters

lpszString
Pointer to a null-terminated wide string.

Return Value

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

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	Retrieves the length of a wide string in wide characters.