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] Source Unicode string for which the client wants the set of code pages.

cchSrc

[in] Number of characters in pszSrc. This must always be specified, even if pszSrc is a null-terminated string.

dwPriorityCodePages

[in] Set of code pages to give priority (see the Remarks section).

pdwCodePages

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

pcchCodePages

[out] Address 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.

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

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

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;
}

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

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