


_XConvertCTToWC(3X11)					_XConvertCTToWC(3X11)
X11R5									X11R5



NAME
  _XConvertCTToWC - conversion from  CT	string to  WC string

SYNOPSIS
  iinntt __XXCCoonnvveerrttCCTTTTooWWCC(_x_l_o_c_a_l_e, _c_t__s_t_r, _c_t__b_y_t_e_s, _w_c__s_t_r, _w_c__l_e_n,
  _s_c_a_n_n_e_d__b_y_t_e_s, _s_t_a_t_e)
  XXLLooccaallee _x_l_o_c_a_l_e;;
  cchhaarr *_c_t__s_t_r;;
  iinntt _c_t__b_y_t_e_s;;
  wwcchhaarr	*_w_c__s_t_r;;
  iinntt *_w_c__l_e_n;;
  iinntt *_s_c_a_n_n_e_d__b_y_t_e_s;;
  __SSttaattee *_s_t_a_t_e;;

ARGUMENTS

  _x_l_o_c_a_l_e   In:	specifies locale, the default NULL is the current locale.

  _c_t__s_t_r    In:	CT string.

  _c_t__b_y_t_e_s  In:	length of CT strings, counted in bytes.

  _w_c__s_t_r    Out: conversion buffer of result wchar string.

  _w_c__l_e_n    In/Out: as "In" it is length of buffer wc_str passed by caller;
	    as "Out" it	is the returned	number of converted wchars.

  _s_c_a_n_n_e_d__b_y_t_e_s
	    Number of CT bytes converted when the function returns.

  _s_t_a_t_e	    In/Out: as "In" it is the state at the beginning of	the CT
	    string; as "Out" it	is the current state stopped at	last con-
	    verted CT encoding.	 The state is defined internally by Xlib.  If
	    this pointer is null, the function will assume the state to	be
	    the	default	CT state. Of course, nothing will be put in the	null
	    pointer. Do	not modify or free this	data.

DESCRIPTION
  The __XXCCoonnvveerrttCCTTTTooWWCC converts the string encoded in CT	to string encoded in
  wchar.  After	a successful conversion, the null character WNULL will be
  appended to wc_str if	there is room for it in	the buffer.  The terminator
  WNULL	of wchar string	is not counted in length of output buffer wc_len.

  The returned state will point	to a state of the encoding in the internal
  table, so do not modify or free this pointer.

  When function	returns	at any time, scanned_bytes always remembers where
  stopped, and state always remembers the current CT state if it is not	null
  pointer.

  The caller of	this function has to provide the output	buffer wc_str, and
  store	the buffer length(in wchars) into wc_len as input. By using
  scanned_bytes	and state, the caller can break	a large	CT string into
  pieces, and convert one piece	at a time.

  In other hand	caller can pass	any broken CT string to	this function for
  doing	conversion.  For example, caller can still be trying of	conversion
  when the error BadBuffer is occurred (output buffer was exhausted).
  Usually, the application passes the NULL to state for	first conversion as
  the following:

       char *state = NULL;
       __XXCCoonnvveerrttCCTTTTooWWCC((NNUULLLL,, cctt__ssttrr,, cctt__lleenn,, mmbb__ssttrr,,
		   &&mmbb__lleenn,, &&ssccaannnneedd,, &&ssttaattee))

  The conversion function returns the value of variable	state to use for the
  conversion of	the next unconverted piece of the same string.	And so on.

  If the value of state	is invalid or null-pointer, the	function will suppose
  the default state of CT as initial.  The default state of CT is defined in
  3 cases of encoding:

    1. no control sequence, GL and GR of Latin-1 is supposed.

    2. control sequence	of Latin-1 GL only, GR of Latin-1 is supposed too.

    3. control sequence	of Latin-1 GR only, GL of Latin-1 is supposed too.

  The function returns the BadBuffer meaning that the output buffer wc_str
  was exhausted.  The function returns the BadTerminate	meaning	that the CT
  string ct_str	is terminated uncompletely, e.g., uncompleted ESC sequence or
  uncompleted code point ended at tail of ct_str.

  Only in both the case	of BadBuffer and BadTerminate the caller can move
  pointer ct_str to (ct_str + *scanned_bytes), then continue to	do conver-
  sion.	 And function ensure that the wc_str stores the	already	converted
  wchar	string;	wc_len counts the number of them in wchars(not bytes); the
  state	stores the last	state of encoding.

  The function returns a number	greater	than zero meaning a number of wrong
  codepoints recovered by the function.	 The wrong codepoint will be
  recovered with the first codepoint of	the charset at which the wrong
  codepoint occurs.  After replaced, the function will continue	to do conver-
  sion until one of the	results	Success, BadTerminate, BadBuffer or BadEncod-
  ing is met.

  The function returns BadEncoding meaning for unrecoverable wrong code	which
  is actually wrong escape sequence, or	not registered by system yet.

  Both the null	character and ct_bytes will terminate the conversion.

  All error status are defined to be less than zero, i.e.:

    #define Success	     0

    #define BadBuffer	    -1

    #define BadTerminate    -2

    #define BadEncoding	    -3

RETURNED VALUE
  The __XXCCoonnvveerrttCCTTTTooWWCC wwiillll rreettuurrnn tthhee ffoolllloowwiinngg	vvaalluueess::

  SSuucccceessss
       successful conversion.

  BBaaddBBuuffffeerr
       output buffer(wc_str) was exhausted.

  BBaaddTTeerrmmiinnaattee
       CT string was terminated	uncompletely.

  BBaaddEEnnccooddiinngg
       wrong codepoints	can not	be recovered.

  >> 00  number of wrong codepoints, but recovered.

SEE ALSO
  Refer	to "CT and WC" for their definitions.




























































