Initializing help system before first use

XNLSopenconv

Purpose
Open a transcoder stream.
Synopsis
XNLSstream XNLSopenconv(int eid, int flags, long (*fsync)(void *vctx,void *fd,void *buf,unsigned long bufsize), void *fd);
Arguments
eid 
Encoding ID of the destination
flags 
Conversion flags:
XNLS_OPT_READ 
Convert to UTF-8
XNLS_OPT_WRITE 
Convert from UTF-8
XNLS_OPT_STRICT 
Fail in case of invalid sequence (otherwise skip it)
XNLS_OPT_NOBOM 
Do not put a BOM when writing (by default a BOM is emitted for UTF-16 and UTF-32) and do not look for a BOM when reading
XNLS_OPT_BOM 
Force BOM (by default no BOM is emitted for UTF-8), option ignored for a reader stream
XNLS_OPT_BSZ(s) 
Size of a internal buffer in kilobytes (must be between 2 and 64, default value: 2)
fsync 
Data reader or writer function
fd 
Data reader/writer file descriptor
Return value
A stream context or NULL in case of error.
Further information
1. When a stream is created for reading ( i.e. option flags is XNLS_OPT_READ), input data is expected to be encoded in the specified encoding eid. The converter gets the stream of data to process from a callback function: the provided read function fsync takes as parameters some general context vctx (provided to XNLSconvread), the file descriptor for this stream (specified with this call as fd) and a buffer buf where it puts up to bufsize bytes of data. This function must return the amount of data transfered, 0 when the end of file has been reached or a negative value to indicate an error condition.
2. When a stream is created for writing ( i.e. option flags is XNLS_OPT_WRITE), output data is encoded in the specified encoding eid. The converter outputs the stream of data it has processed using a callback function: the provided write function fsync takes as parameters some general context vctx (provided to XNLSconvwrite), the file descriptor for this stream (specified with this call as fd) and a buffer buf of bufsize bytes of data to save. This function is expected to return a non-zero value on success ( i.e. all data has been saved) and 0 on failure.
3. The option XNLS_OPT_NOBOM tells the routine not to try to find a BOM (Byte Order Mark) when opening a stream for reading. This BOM consists in a sequence of bytes at the beginning of the stream to identify the Unicode encoding used for the stream. Unless the option XNLS_OPT_NOBOM is used, this BOM detection is effective when the selected encoding is Unicode (either UTF-8, UTF-16 or UTF-32). When applied to a stream open for writing, this option disables the insertion of a BOM when creating a stream encoded in UT-F16 or UTF-32 (it is gnored for all other encodings).
4. The option XNLS_OPT_BOM forces the insertion of the BOM when openning a stream encoded in UTF-8 for writing (this encoding usually does not require a BOM).
Related topics
XNLScloseconv.

Parent Topic Stream encoding conversion

© 2001-2025 Fair Isaac Corporation. All rights reserved. This documentation is the property of Fair Isaac Corporation (“FICO”). Receipt or possession of this documentation does not convey rights to disclose, reproduce, make derivative works, use, or allow others to use it except solely for internal evaluation purposes to determine whether to purchase a license to the software described in this documentation, or as otherwise set forth in a written software license agreement between you and FICO (or a FICO affiliate). Use of this documentation and the software described in it must conform strictly to the foregoing permitted uses, and no other use is permitted.