Layout Service Library Functions m_transform_layout(3LAYOUT)
NAME
m_transform_layout - layout transformation
SYNOPSIS
cc [ flag... ] file... -llayout [ library... ]
#include
int m_transform_layout(LayoutObject layout_object,
const char *InpBuf, const size_t ImpSize, const void *OutBuf,
size_t *Outsize, size_t *InpToOut, size_t *OutToInp,
unsigned char *Property, size_t *InpBufIndex);
DESCRIPTION
The m_transform_layout() function performs layout transfor-
mations (reordering, shaping, cell determination) or pro-
vides additional information needed for layout transforma-
tion (such as the expected size of the transformed layout, the nesting level of different segments in the text andcross-references between the locations of the corresponding
elements before and after the layout transformation). Both the input text and output text are character strings.The m_transform_layout() function transforms the input text
in InpBuf according to the current layout values inlayout_object. Any layout value whose value type is Layout-
TextDescriptor describes the attributes of the InpBuf and OutBuf arguments. If the attributes are the same for both InpBuf and OutBuf, a null transformation is performed with respect to that specific layout value.The InpBuf argument specifies the source text to be pro-
cessed. The InpBuf may not be NULL, unless there is a need to reset the internal state. The InpSize argument is the number of bytes within InpBuf to be processed by the transformation. Its value will not change after return from the transformation. InpSize set to-1 indicates that the text in InpBuf is delimited by a null
code element. If InpSize is not set to -1, it is possible to
have some null elements in the input buffer. This might be used, for example, for a "one shot" transformation of several strings, separated by nulls. Output of this function may be one or more of the following depending on the setting of the arguments:SunOS 5.11 Last change: 7 Aug 2006 1
Layout Service Library Functions m_transform_layout(3LAYOUT)
OutBuf Any transformed data is stored in OutBuf, con-
verted to ShapeCharset. Outsize The number of bytes in OutBuf.InpToOut A cross-reference from each InpBuf code element
to the transformed data. The cross-reference
relates to the data in InpBuf starting with the first element that InpBufIndex points to (and not necessarily starting from the beginning of the InpBuf).OutToInp A cross-reference to each InpBuf code element
from the transformed data. The cross-reference
relates to the data in InpBuf starting with the first element that InpBufIndex points to (and not necessarily starting from the beginning of the InpBuf). Property A weighted value that represents peculiar input string transformation properties with differentconnotations as explained below. If this argu-
ment is not a null pointer, it represents an array of values with the same number of elements as the source substring text before the transformation. Each byte will contain relevant"property" information of the corresponding ele-
ment in InpBuf starting from the element pointed by InpBufIndex. The four rightmost bits of each "property" byte will contain information forbidirectional environments (when ActiveDirec-
tional is True) and they will mean "NestingLev-
els." The possible value from 0 to 15 represents the nesting level of the corresponding element in the InpBuf starting from the element pointed by InpBufIndex. If ActiveDirectional is false the content of NestingLevel bits will be ignored. The leftmost bit of each "property" byte will contain a "new cell indicator" for composed character environments, and will have a value of either 1 (for an element in InpBuf that is transformed to the beginning of a new cell)or 0 (for the "zero-length" composing character
elements, when these are grouped into the samepresentation cell with a non-composing charac-
ter). Here again, each element of "property" pertains to the elements in the InpBuf starting from the element pointed by InpBufIndex.SunOS 5.11 Last change: 7 Aug 2006 2
Layout Service Library Functions m_transform_layout(3LAYOUT)
(Remember that this is not necessarily thebeginning of InpBuf). If none of the transforma-
tion properties is required, the argument Pro-
perty can be NULL. The use of "property" can beenhanced in the future to pertain to other pos-
sible usage in other environments. The InpBufIndex argument is an offset value to the locationof the transformed text. When m_transform_layout() is
called, InpBufIndex contains the offset to the element in InpBuf that will be transformed first. (Note that this is not necessarily the first element in InpBuf). At the return from the transformation, InpBufIndex contains the offset to the first element in the InpBuf that has not been transformed. If the entire substring has been transformed successfully, InpBufIndex will be incremented by the amount defined by InpSize. Each of these output arguments may be NULL to specify that no output is desired for the specific argument, but at leastone of them should be set to a non-null value to perform any
significant work. The layout object maintains a directional state that keeps track of directional changes, based on the last segment transformed. The directional state is maintained across calls to the layout transformation functions and allows stream data to be processed with the layout functions. The directional state is reset to its initial state whenever any of the layout values TypeOfText, Orientation, or ImplicitAlgis modified by means of a call to m_setvalues_layout().
The layout_object argument specifies a LayoutObject returned
by the m_create_layout() function.
The OutBufargument contains the transformed data. This argu-
ment can be specified as a null pointer to indicate that no transformed data is required. The encoding of the OutBuf argument depends on theShapeCharset layout value defined in layout_object. If the
ActiveShapeEditing layout value is not set (False), the encoding of OutBuf is guaranteed to be the same as the codeset of the locale associated with the LayoutObjectdefined by layout_object.
SunOS 5.11 Last change: 7 Aug 2006 3
Layout Service Library Functions m_transform_layout(3LAYOUT)
On input, the OutSize argument specifies the size of the output buffer in number of bytes. The output buffer shouldbe large enough to contain the transformed result; other-
wise, only a partial transformation is performed. If the ActiveShapeEditing layout value is set (True) the OutBufshould be allocated to contain at least the InpSize multi-
plied by ShapeCharsetSize. On return, the OutSize argument is modified to the actual number of bytes placed in OutBuf. When the OutSize argument is specified as zero, the functioncalculates the size of an output buffer large enough to con-
tain the transformed text, and the result is returned in this field. The content of the buffers specified by InpBuf and OutBuf, and the value of InpBufIndex, remain unchanged. If OutSize = NULL, the EINVAL error condition should be returned. If the InpToOut argument is not a null pointer, it points to an array of values with the same number of bytes in InpBuf starting with the one pointed by InpBufIndex and up to the end of the substring in the buffer. On output, the nth value in InpToOut corresponds to the nth byte in InpBuf. Thisvalue is the index (in units of bytes) in OutBufthat identi-
fies the transformed ShapeCharset element of the nth byte in InpBuf. In the case of multibyte encoding, the index points (for each of the bytes of a code element in the InpBuf) tothe first byte of the transformed code element in the Out-
Buf. InpToOut may be specified as NULL if no index array from InpBuf to OutBuf is desired. If the OutToInp argument is not a null pointer, it points toan array of values with the same number of bytes as con-
tained in OutBuf. On output, the nth value in OutToInp corresponds to the nth byte in OutBuf This value is theindex in InpBuf, starting with the byte pointed to by Inp-
BufIndex, that identifies the logical code element of the nth byte in OutBuf. In the case of multibyte encoding, the index will point for each of the bytes of a transformed code element in the OutBuf to the first byte of the code element in the InpBuf.SunOS 5.11 Last change: 7 Aug 2006 4
Layout Service Library Functions m_transform_layout(3LAYOUT)
OutToInp may be specified as NULL if no index array from OutBuf to InpBuf is desired. To perform shaping of a text string without reordering ofcode elements, the layout_object should be set with input
and output layout value TypeOfText set to TEXT_VISUAL and
both in and out of Orientation set to the same value.RETURN VALUES
If successful, the m_transform_layout() function returns 0.
If unsuccessful, the returned value is -1 and the errno is
set to indicate the source of error. When the size of OutBuf is not large enough to contain the entire transformed text,the input text state at the end of the uncompleted transfor-
mation is saved internally and the error condition E2BIG is returned in errno.ERRORS
The m_transform_layout() function may fail if:
E2BIG The output buffer is full and the source text is not entirely processed.EBADF The layout values are set to a meaningless combi-
nation or the layout object is not valid.EILSEQ Transformation stopped due to an input code ele-
ment that cannot be shaped or is invalid. The Inp-
BufIndex argument is set to indicate the code ele-
ment causing the error. The suspect code element is either a valid code element but cannot be shaped into the ShapeCharset layout value, or is an invalid code element not defined by the codesetof the locale of layout_object. The mbtowc() and
wctomb() functions, when used in the same locale as the LayoutObject, can be used to determine if the code element is valid.EINVAL Transformation stopped due to an incomplete compo-
site sequence at the end of the input buffer, or OutSize contains NULL. ERANGE More than 15 embedding levels are in source text or InpBuf contain unbalanced directional layout information (push/pop) or an incomplete composite sequence has been detected in the input buffer at the beginning of the string pointed to bySunOS 5.11 Last change: 7 Aug 2006 5
Layout Service Library Functions m_transform_layout(3LAYOUT)
InpBufIndex. An incomplete composite sequence at the end of the input buffer is not always detectable. Sometimes, the fact that the sequence is incomplete will only be detected when additional character elements belonging to the composite sequence are found at the beginning of the next input buffer.USAGE
A LayoutObject will have a meaningful combination of default layout values. Whoever chooses to change the default layout values is responsible for making sure that the combination of layout values is meaningful. Otherwise, the result ofm_transform_layout() might be unpredictable or
implementation-specific with errno set to EBADF.
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Committed ||_____________________________|_____________________________|
| MT-Level | MT-Safe |
|_____________________________|_____________________________|
| Standard | See standards(5). ||_____________________________|_____________________________|
SEE ALSO
attributes(5), standards(5)SunOS 5.11 Last change: 7 Aug 2006 6