IMLangCodePages::GetStrCodePages Method

---

Retrieves the set of code pages to which the Unicode characters in the given string belong.

Syntax

HRESULT GetStrCodePages(
    const WCHAR *pszSrc,
    long cchSrc, 
    DWORD dwPriorityCodePages,
    DWORD *pdwCodePages,
    long *pcchCodePages
); 

Parameters

pszSrc

[in] Address of a source Unicode string for which the client wants the set of code pages.

cchSrc

[in] Integer that specifies the number of characters in pszSrc. This must always be specified, even if pszSrc is a null-terminated string.

dwPriorityCodePages

[in] Unsigned long integer that specifies a set of code pages to give priority (see the Remarks section).

pdwCodePages

[out] Address of an unsigned long integer where the set of code pages that contain the characters in the given string is returned.

pcchCodePages

[out] Address on an integer where the number of characters that have been processed is returned.

Return Value

Returns one of the following values:

S_OK	Success.
E_INVALIDARG	The given string is invalid, or cchSrc is not positive.
E_FAIL	An unexpected error occurred.

Remarks

See IMLangCodePages for more information about sets of code pages.

The set of code pages that is returned to pdwCodePages will be the intersection of each character's set of code pages. For example, assume there are three characters (A, B, and C) in the given string, with the set of code pages as follows:

Character A:	Latin1, Latin2, Greek, Turkish, Hebrew, and Japanese.
Character B:	Latin1, Greek, Turkish, and Korean.
Character C:	Latin2, Greek, Turkish, and Japanese.

In this case, Greek and Turkish will be returned into pdwCodePages because all three character sets contain A, B, and C. The actual code page identifier values for these pages can be retrieved by the IMLangCodePages::CodePagesToCodePage method.

In addition, assume another character (D) follows characters A, B, and C in the given string, and the set of code pages of character D is:

Character D:

Latin1, Cyrillic, Hebrew, Japanese, and Korean.

The intersection of characters A, B, C, and D is the empty set. In this case, the method returns 3 in pcchCodePages, which represents the number of characters processed, and it also returns the intersection of the code pages of characters A, B, and C in pdwCodePages.

The dwPriorityCodePages parameter should be zero if no code pages have special priority. However, this parameter is ideally used to avoid inconsistency in splitting strings. Using the example above, if dwPriorityCodePages is Latin1, the method performs as follows:

String	pcchCodePages	pdwCodePages
ABCD	2	Latin1, Greek, Turkish.
CD	1	Latin2, Greek, Turkish, and Japanese.
D	1	Latin1, Cyrillic, Hebrew, Japanese, and Korean.

Because character C is not in the Latin1 character set, pcchCodePages for string ABCD is 2, not 3. In the same way, if dwPriorityCodePages is Japanese, the method performs as follows:

String	pcchCodePages	pdwCodePages
ABCD	1	Latin1, Latin2, Greek, Turkish, Hebrew, and Japanese.
BCD	1	Latin1, Greek, Turkish, and Korean.
CD	2	Japanese.

Windows CE

Windows CE	Use version 2.12 and later
Minimum availability	Internet Explorer 4.0

Example

This example calls GetStrCodePages on the Unicode string pszSrc with dwACP set as the code page that is given priority. Note how the method might have to be called multiple times to gather the code pages for the entire string.

Sample Code

// pszSrc - null-terminated Unicode string.

int cchDone = 0;
int cchSrc = lstrlen(pszSrc);
DWORD dwACP;

// Give priority to CP_ACP.
pMLangCodePages->CodePageToCodePages(CP_ACP, &dwACP);

while (cchDone < cchSrc)
{
    DWORD dwCodePages;
    int cchCodePages;

    pMLangCodePages->GetStrCodePages(pszSrc + cchDone,
        cchSrc - cchDone, dwACP, &dwCodePages, &cchCodePages);

    // Do something based on dwCodePages.

    cchDone += cchCodePages;
}