A Reference Document on CHNCONV.DLL

by HARIGAYA Soichi



Contents



Functions


CHNCONV.DLL is a thread-safe program. All functions on this documents are designed to run safely on multi-thread programs. (Some obsolete functions, which are not on this document, are not thread-safe.)
 

  int WINAPI ChnconvEx (
      LPCTSTR               pSrcFileName,
      LPCTSTR               pDstFileName,
      int                   nSrcCodePage,
      int                   nDstCodePage,
      const CHNCONVEXINFO * pChnconvExInfo
  ) ;

ChnconvEx performs conversion of Chinese character codes. This is the main interface of CHNCONV.DLL. If the macro "UNICODE" is defined and included "chnconv.h", the macro "ChnconvEx" will be replaced by the Unicode version "ChnconvExW". Otherwise, the macro ChnconvEx will be replaced by the Ansi version "ChnconvExA".


/**** Parameters ****/

  LPCTSTR pSrcFileName    /* Source filename      */
  LPCTSTR pSrcFileName    /* Destination filename */
Specifies the filename of the source and the destination. A filename may be a full pathname, a relative pathname, or a UNC. If the filename is NULL, the function will open stdin or stdout.
Supported file format types are a Text file or a RTF (Rich Text File).

  int nSrcCodePage      /* Source code page      */
  int nDstCodePage      /* Destination code page */
Specifies the code page of the source and the destination. 
        GB2312/GBK                 936
        BIG5                       950
        Chinese Writer             932 + 0x10000
        Nihao                      932 + 0x20000
        cWnn                       932 + 0x30000
        Zhongwen Qigao             932 + 0x40000
        CX                         932 + 0x50000
        KOA-TechnoMate Zhongguoyu  932 + 0x60000
        Zhuojue                    932 + 0x70000
        Front Wenhua               932 + 0x80000
        HZ                         52936
These codepages are defined with the following names in "chnconv.h". 
        GB2312/GBK                 CP_CHINESE_SIMPLIFIED
        BIG5                       CP_CHINESE_TRADITIONAL
        Chinese Writer             CP_CHINESE_CW
        Nihao                      CP_CHINESE_NH
        cWnn                       CP_CHINESE_CWN
        Zhongwen Qigao             CP_CHINESE_ZQ
        CX                         CP_CHINESE_CX
        KOA-TechnoMate Zhongguoyu  CP_CHINESE_TM
        Zhuojue                    CP_CHINESE_ZJ
        Front Wenhua               CP_CHINESE_FW
        HZ                         CP_HZ_CHINESE_SIMPLIFIED


  const CHNCONVEXINFO * pChnconvExInfo      /* Options */
Pointer to a CHNCONVEXINFO structure that determines the options of conversion. If this parameter is NULL, the function will perform default conversion.


/**** Return Values ****/

The return value is one of the following values.

CHNCONV_SUCCESS
Conversion was successful.

CHNCONV_ERROR_UNKNOWN
Occurred unknown errors.

CHNCONV_ERROR_READ
Failed to read the source file.

CHNCONV_ERROR_WRITE
Failed to write the destination file.

CHNCONV_ERROR_RTFFORMAT
Occurred errors of RTF format.

CHNCONV_ERROR_RTFBRACE
Occurred errors of RTF format.

CHNCONV_ERROR_MEMORY
Failed to allocate required memory.

CHNCONV_ERROR_CODEPAGE
The code page is invalid.

CHNCONV_ERROR_ABORTED
Aborted by AbortChnconv during conversion.

CHNCONV_ERROR_PARAM
Specified parameters are invalid.

You can also get these return values by GetChnconvLastError.





  intptr_t WINAPI ChnconvStringEx (
      const char *          pSrcBuffer,
      char *                pDstBuffer,
      int                   nSrcCodePage,
      int                   nDstCodePage,
      const CHNCONVEXINFO * pChnconvExInfo,
      size_t nMaxLen
  ) ;

This function performs character-code conversion of strings.


/**** Parameters ****/

  const char * pSrcBuffer    /* Pointer to the source string */
  char * pDstBuffer          /* Pointer to the destination buffer */
Specifies the pointer to the source string and the destination buffer. The string pointed to by pSrcBuffer must be null-terminated. If the same address is specified to pSrcBuffer and pDstBuffer, the result of conversion is undefined.

If pDstBuffer is NULL, the function will not perform conversion, and returns the required size of destination buffer in bytes.
  int nSrcCodePage                     /* Source codepage */
  int nDstCodePage                     /* Destination codepage */
Specifies the code page of the source and the destination. See nSrcCodePage and nDstCodePage of ChnconvEx for more information. 
  const CHNCONVEXINFO * pChnconvExInfo      /* Options */
Pointer to a CHNCONVEXINFO structure that determines the options of conversion. If this parameter is NULL, the function will perform default conversion.

  size_t nMaxLen            /* Size of destination buffer */
Specifies the size of destination buffer, in bytes.


/**** Return Value ****/

The return value is the number of bytes written to the buffer pointed to by pDstBuffer.
If it failed to convert, it would return -1. To get more information, call GetChnconvLastError.

If pDstBuffer is NULL, it would return the required size of destination buffer in bytes.





  int WINAPI ChnconvCharEx (
      int C,
      int nSrcCodePage,
      int nDstCodePage,
      const CHNCONVEXINFO *pChnconvExInfo
  ) ;

This function converts a character to other codepages.


/**** Parameters ****/
  int C                                   /* Character */
Specifies a character code.
  int nSrcCodePage                        /* Source codepage */
  int nDstCodePage                        /* Destination codepage */
Specifies the code page of the source and the destination. See nSrcCodePage and nDstCodePage of ChnconvEx for more information. 
  const CHNCONVEXINFO * pChnconvExInfo      /* Options */
Pointer to a CHNCONVEXINFO structure that determines the options of conversion. If this parameter is NULL, the function will perform default conversion.


/**** Return Value ****/

The return value is a character.
If it failed to convert, it would return -1. To get more information, call GetChnconvLastError. 





  int WINAPI IsChnconvValidCodePage (
      int nSrcCodePage,
      int nDstCodePage
  ) ;

Test whether CHNCONV.DLL supports a specified code page. See nSrcCodePage and nDstCodePage of ChnconvEx for more information.


/**** Return Value ****/

If the specified codepage is supported, return 1.
If the specified codepage is not supported, return 0.






  int WINAPI GetChnconvLastError (
      void
  ) ;

Get the calling thread's last-error code of ChnconvEx, ChnconvStringEx, or ChnconvCharEx.


/**** Return Values ****/

The return value is one of the following values.

CHNCONV_SUCCESS
Conversion was successful.

CHNCONV_ERROR_UNKNOWN
Occurred unknown errors.

CHNCONV_ERROR_READ
Failed to read the source file.

CHNCONV_ERROR_WRITE
Failed to write the destination file.

CHNCONV_ERROR_RTFFORMAT
Occurred errors of RTF format.

CHNCONV_ERROR_RTFBRACE
Occurred errors of RTF format.

CHNCONV_ERROR_MEMORY
Failed to allocate required memory.

CHNCONV_ERROR_CODEPAGE
The code page is invalid.

CHNCONV_ERROR_ABORTED
Aborted by AbortChnconv during conversion.

CHNCONV_ERROR_PARAM
Specified parameters are invalid.






  int WINAPI AbortChnconv (
      void
  ) ;

If you call this function while ChnconvEx or ChnconvStringEx is running in the process, these functions may stop conversion and return an error-code. AbortChnconv will affect all threads of the process.


/**** Return Value ****/

The return value is always 0.





  int WINAPI GetDllVersion (
      void
  ) ;

Get the version of CHNCONV.DLL.


/**** Return Value ****/

If the version of CHNCONV.DLL is 5.31, the function returns 531.

Structures
 

  typedef struct {
        size_t                  cbSize ;
        unsigned long           dwConversionMode ;
        unsigned long           dwAdditionalMode ;
        const CHNFONTINFO *     pFontInfo ;
        const CHNCONV_USERDEF * pSrcToDst ;
        size_t                  nNumberOfSrcToDst ;
        const CHNCONV_USERDEF * pSrcToUc ;
        size_t                  nNumberOfSrcToUc ;
        int                     nFontSize ;
        const void *            pReserved ;
  } CHNCONVEXINFO ;

/**** Members ****/

cbSize
Specifies the length, in bytes, of the structure.

dwConversionMode
Specifies a combination of the following flag constants. If this member is 0, the function will perform conversion with default options.

CONVMODE_PEEKMESSAGE
Peek messages during conversion.

CONVMODE_OUTPUT_CODE_NUMBER
Write its Code Number for unmappable characters.

CONVMODE_INPUT_CODE_NUMBER
Recognize Code Numbers which are written by option CONVMODE_OUTPUT_CODE_NUMBER.

CONVMODE_ONE_QUESTION_MARK
Write one question mark '?' if cannot convert. If not specified this flag, the function will write two question marks for full-width characters.

CONVMODE_CONVERT_TXT
Read files as plain text compulsorily.

CONVMODE_CONVERT_RTF
Read files as rich text format compulsorily.

CONVMODE_CHNCONV_NO_VARIANT
Do not search for character variants.

CONVMODE_CHNCONV_NO_GBK
Do not convert GBK extended characters.

CONVMODE_PINYIN_BY_ASCII
Write pinyin characters by single-byte font on writing RTF.

CONVMODE_OUTPUT_NEW_FONT
Write new font names on writing RTF of Chinese Writer.

CONVMODE_SENSE_CW_FANTIZI
Sense CW/CWN FANTIZI font on reading RTF.

CONVMODE_CW_TXT_FANTIZI
Read CW/CWN text files as FANTIZI.

CONVMODE_NO_USE_UNICODE
Do not use Unicode on converting characters.

dwAdditionalMode
Reserved. Set this member to zero.

pFontInfo
Specifies the pointer to the CHNFONTINFO structure. If this member is NULL, the function will use the default font face names on writing RTF.

pSrcToDst
Specifies the pointer to the array of CHNCONV_USERDEF structure, which defines the user-defined character conversion from the source codepage to the destination codepage. If this member is NULL, the function will use the default character conversion.

nNumberOfSrcToDst
Specifies the length of array of CHNCONV_USERDEF structure, which is specified to pSrcToDst member. If the pSrcToDst member is NULL, set this member to 0.

pSrcToUc
Specifies the pointer to the array of CHNCONV_USERDEF structure, which defines the user-defined character conversion from the source codepage to Unicode. If this member is NULL, the function will use the default character conversion.

nNumberOfSrcToUc
Specifies the length of array of CHNCONV_USERDEF structure, which is specified to pSrcToUc member. If the pSrcToUc member is NULL, set this member to 0.

nFontSize
Specifies the font size for writing RTF. This member is valid only on converting KOA-TechnoMate Zhongguoyu files or Front Wenhua files. If this member is 0, the function will write the default font size.

pReserved
Reserved. Set this member to NULL.





  typedef struct {
        size_t cbSize ;
        const char *pGbFont ;
        const char *pGbGothicFont ;
        const char *pBig5Font ;
        const char *pBig5GothicFont ;
        const char *pPinyinFont ;
        const char *pPinyinGothicFont ;
  } CHNFONTINFO ;

/**** Members ****/

cbSize
Specifies the length, in bytes, of the structure.

pGbFont
Specifies the font face name for GB characters, which will be used on writing RTF. If this member is NULL, the function will use the default font face name.

pGbGothicFont
Specifies the font face name for GB Sans-Serif characters, which will be used on writing RTF. If this member is NULL, the function will use the default font face name.

pBig5Font
Specifies the font face name for BIG5 characters, which will be used on writing RTF. If this member is NULL, the function will use the default font face name.

pBig5GothicFont
Specifies the font face name for BIG5 Sans-Serif characters, which will be used on writing RTF. If this member is NULL, the function will use the default font face name.

pPinyinFont
Specifies the font face name for Pinyin characters, which will be used on writing RTF. If this member is NULL, the function will use the default font face name. This member will be ignored if the flag CONVMODE_PINYIN_BY_ASCII is not specified to dwConversionMode of CHNFONTINFO structure.

pPinyinGothicFont
Specifies the font face name for Pinyin Sans-Serif characters, which will be used on writing RTF. If this member is NULL, the function will use the default font face name. This member will be ignored if the flag CONVMODE_PINYIN_BY_ASCII is not specified to dwConversionMode of CHNFONTINFO structure.





  typedef struct {
        int   nSrc ;
        int   nDst ;
  } CHNCONV_USERDEF ;

/**** Members ****/

nSrc
Specifies a source character.

nDst
Specifies a destination character.

Sample

/**** Sample 1 ****/

/* Convert a Chinese Writer RTF file to GB.  */

#include <windows.h>
#include "chnconv.h"

typedef int (WINAPI *CHNCONVEX) ( LPCTSTR pSrcFileName, LPCTSTR pDstFileName,
     int nSrcCodePage, int nDstCodePage, const CHNCONVEXINFO *pChnconvExInfo ) ;


int main () {

    /* DLL */
    HINSTANCE hChnconv ;
    CHNCONVEX pChnconvEx ;

    /* Reading DLL */
    hChnconv = LoadLibrary( TEXT("chnconv.dll") ) ;
    if ( hChnconv == NULL ) {
        return 1 ;
    }

#ifdef UNICODE
    pChnconvEx = (CHNCONVEX) GetProcAddress( hChnconv, "ChnconvExW" ) ;
#else
    pChnconvEx = (CHNCONVEX) GetProcAddress( hChnconv, "ChnconvExA" ) ;
#endif
    if ( pChnconvEx == NULL ) {
        FreeLibrary( hChnconv ) ;
        return 1 ;
    }

    /* Conversion */
    pChnconvEx ( TEXT("c:\\foo.rtf"), TEXT("c:\\poo.rtf"), CP_CHINESE_CW, CP_CHINESE_SIMPLIFIED, NULL ) ;

    /* Finalization */
    FreeLibrary( hChnconv ) ;
    return 0 ;
}



/**** Sample 2 ****/

/* Convert a cWnn string to GB.  */

#include <windows.h>
#include "chnconv.h"

typedef intptr_t (WINAPI *CHNCONVSTRINGEX) ( const void *pSrcBuffer, void *pDstBuffer,
      int nSrcCodePage, int nDstCodePage, const CHNCONVEXINFO *pChnconvExInfo,
      size_t nMaxLen ) ;


int main () {

    char szGbBuffer [ 0x100 ] ;
    wchar_t szUcBuffer [ 0x100 ] ;

    /* DLL */
    HINSTANCE hChnconv ;
    CHNCONVSTRINGEX pChnconvStringEx ;

    /* Reading DLL */
    hChnconv = LoadLibrary( TEXT("chnconv.dll") ) ;
    if ( hChnconv == NULL ) {
        return 1 ;
    }

    pChnconvStringEx = (CHNCONVSTRINGEX) GetProcAddress( hChnconv, "ChnconvStringEx" ) ;
    if ( pChnconvStringEx == NULL ) {
        FreeLibrary( hChnconv ) ;
        return 1 ;
    }

    /* Convert to GB */
    pChnconvStringEx( "\x9B\xCE\x8D\x9A", szGbBuffer, CP_CHINESE_CWN, CP_CHINESE_SIMPLIFIED, 0, sizeof(szGbBuffer) );

    /* Convert to UNICODE */
    MultiByteToWideChar ( CP_CHINESE_SIMPLIFIED, 0, szGbBuffer, -1, szUcBuffer, sizeof(szUcBuffer)/sizeof(wchar_t) ) ;

    /* Display */
    MessageBoxW( NULL, szUcBuffer, L"test", MB_OK ) ;

    /* Finalization */
    FreeLibrary( hChnconv ) ;
    return 0 ;
}



/**** Sample 3 ****/

/* Convert a cWnn character to GB.  */

#include <windows.h>
#include <stdio.h>
#include "chnconv.h"

typedef intptr_t (WINAPI *CHNCONVCHAREX) ( int C, int nSrcCodePage, int nDstCodePage,
      int nSrcCodePage, int nDstCodePage, const CHNCONVEXINFO *pChnconvExInfo ) ;


int main () {

    int C ;

    /* DLL */
    HINSTANCE hChnconv ;
    CHNCONVCHAREX pChnconvCharEx ;

    hChnconv = LoadLibrary( "chnconv.dll" ) ;
    if ( hChnconv == NULL ) return 1 ;

    pChnconvCharEx = (CHNCONVSTRING) GetProcAddress( hChnconv, "ChnconvCharEx" ) ;
    if ( pChnconvCharEx == NULL ) {
        FreeLibrary( hChnconv ) ;
        return 1 ;
    }

    C = pChnconvCharEx( 0x9BCE, CP_CHINESE_CWN, CP_CHINESE_SIMPLIFIED, NULL );
    if ( C <= 0 ) {
        FreeLibrary( hChnconv ) ;
        return 1 ;
    }

    if ( C & 0xFF00 ) fputc( ( C >> 8 ) & 0xFF, stdout ) ;
    fputc( C & 0xFF, stdout ) ;

    FreeLibrary( hChnconv ) ;
    return 0 ;
}



/**** Sample 4 ****/

/* Convert a Chinese Writer RTF file to GB, with "STKaiti" to CJK characters. */

#include <windows.h>
#include "chnconv.h"

typedef int (WINAPI *CHNCONVEX) ( LPCTSTR pSrcFileName, LPCTSTR pDstFileName,
     int nSrcCodePage, int nDstCodePage, const CHNCONVEXINFO *pChnconvExInfo ) ;


int main () {

    /* DLL */
    HINSTANCE hChnconv ;
    CHNCONVEX pChnconvEx ;

    /* Structures */
    CHNCONVEXINFO ChnconvExInfo = { sizeof(CHNCONVEXINFO) } ;
    CHNFONTINFO FontInfo = { sizeof(CHNFONTINFO) } ;

    /* Reading DLL */
    hChnconv = LoadLibrary( TEXT("chnconv.dll") ) ;
    if ( hChnconv == NULL ) {
        return 1 ;
    }

#ifdef UNICODE
    pChnconvEx = (CHNCONVEX) GetProcAddress( hChnconv, "ChnconvExW" ) ;
#else
    pChnconvEx = (CHNCONVEX) GetProcAddress( hChnconv, "ChnconvExA" ) ;
#endif
    if ( pChnconvEx == NULL ) {
        FreeLibrary( hChnconv ) ;
        return 1 ;
    }

    /* Options */
    FontInfo.pGbFont = "STKaiti" ;
    ChnconvExInfo.pFontInfo = & FontInfo ;

    /* Conversion */
    pChnconvEx ( TEXT("c:\\foo.rtf"), TEXT("c:\\poo.rtf"), CP_CHINESE_CW, CP_CHINESE_SIMPLIFIED, & ChnconvExInfo ) ;

    /* Finalization */
    FreeLibrary( hChnconv ) ;
    return 0 ;
}