IMLangCodePages::GetStrCodePages method

Gets the set of code pages that the Unicode characters in the given string belong to.

Syntax

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

Parameters

• pszSrc [in]
  A pointer to a source Unicode string for which the client wants the set of code pages.

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

• dwPriorityCodePages [in]
  An unsigned long integer that specifies a set of code pages to give priority.

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

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

Return value

Returns one of the following values.

Return code	Description
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 is 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 following set of 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 case, Greek and Turkish are 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 using the IMLangCodePages::CodePagesToCodePage method.

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

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. The method 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 used to avoid inconsistency in splitting strings. Using the preceding example, 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.

 

Examples

This example calls GetStrCodePages 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 of cchMax characters or less.

size_t cchDone = 0;
size_t cchMax = 5000;
size_t cchLength;

WCHAR pszSrc[cchMax] = L("some source string");
HRESULT hr = StringCchLengthW(pszSrc, cchMax, &cchLength);

if(SUCCEEDED(hr))
{
   size_t cchSrc = cchLength;
   DWORD dwACP;

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

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

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

       // Do something based on dwCodePages.

       cchDone += cchCodePages;
   }
}
else
{
   //  TODO: Add error handling code here.
}

Requirements

Minimum supported client	Windows XP
Minimum supported server	Windows 2000 Server
Header	Mlang.h
IDL	Mlang.idl
DLL	Mlang.dll

See also

IMLangCodePages