IMLangCodePages::GetStrCodePages (Windows Embedded CE 6.0)

1/6/2010

This 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] Pointer to a source Unicode string for which the client wants the set of code pages.

• cchSrc
  [in] Integer that specifies the number of characters in the source Unicode string specified by the pszSrc parameter. This value must always be specified, even if the source Unicode string is a null-terminated string.

• dwPriorityCodePages
  [in] Specifies a set of code pages to give priority. For more information, see the Remarks section.

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

• pcchCodePages
  [out] Pointer to an integer where the number of characters that have been processed is returned.

Return Value

The following table shows the possible return values for this method.

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

Remarks

For more information about sets of code pages, see IMLangCodePages.

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 that there are three characters A, B, and C in the given string and that the following table shows the set of code pages of these characters.

Character	Code Pages
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 example, Greek and Turkish will be returned into pdwCodePages because these 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 that the following table shows the set of code pages of character D.

Character	Code Pages
Character D:	Latin1, Cyrillic, Hebrew, Japanese, and Korean.

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

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 earlier example, if the value of the dwPriorityCodePages parameter is Latin1, the following table shows the behavior of the method.

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, the value of the pcchCodePages parameter for string ABCD is 2, not 3. In the same way, if the value of the dwPriorityCodePages parameter is Japanese, the following table shows the behavior of the method.

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

Example Code

The following example shows the syntax for calling this method on the Unicode string pszSrc with dwACP set as the code page that is given priority. Note that the method might have to be called multiple times to gather the code pages for the entire string.

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

Requirements

Header	mlang.h, mlang.idl
Library	mlang.dll
Windows Embedded CE	Windows CE .NET 4.0 and later

See Also

Reference

IMLangCodePages