Input/Output

Classes and functions reading and writing byte streams. More...

Data Structures
struct	DasBuf
	Buffer class to handle accumulating byte streams. More...
struct	DasCodec
	Reading and writing array data to buffers. More...
struct	das_credential
	A single credential. More...
struct	DasCredMngr
	Credentials manager Handles a list of login credentials and supplies these as needed for network operations. More...
class	DasEncoding
	Reading and writing values to buffers. More...
struct	das_url
	A parsed URL structure. More...
struct	DasHttpResp
	Encapsulates the status of a HTTP resource request. More...
struct	DasIO
	Tracks input and output operations for das2 stream headers and data. More...

Typedefs
typedef bool(*	das_prompt) (const char *sServer, const char *sRealm, const char *sDataset, const char *sMessage, char *sUser, char *sPassword)
	Function signature for swapping out the user-prompt for credentials acquisition.

Functions
DAS_API int	DasCodec_encode (DasCodec *pThis, DasBuf *pBuf, int nDim, ptrdiff_t *pLoc, int nExpect, uint32_t uFlags)
	Write values from an array into a buffer, does not change the array.
DAS_API char *	das_ssl_getErr (const void *vpSsl, int nRet)
	Get a new string allocated on the heap explaining an SSL error or NULL in nRet == 0.
DAS_API DasErrCode	DasCodec_init (bool bRead, DasCodec *pThis, DasAry *pAry, const char *sSemantic, const char *sEncType, int16_t uSzEach, ubyte cSep, das_units epoch, const char *sOutFmt)
	Initialize a serial buffer decoder/encoder.
DAS_API DasErrCode	DasCodec_update (bool bRead, DasCodec *pThis, const char *sEncType, int16_t uSzEach, ubyte cSep, das_units epoch, const char *sOutFmt)
	Update external aspects of a serial buffer decoder/encoder.
DAS_API void	DasCodec_eatSpace (DasCodec *pThis, bool bEat)
	Set codec to eat extra whitespace, ignored for not text decoding.
DAS_API void	DasCodec_setTrim (DasCodec *pThis, bool bTrim)
	Enable/disable ltrim+rtrim of decoded values (var-width utf8, default on).
DAS_API bool	DasCodec_isTrim (const DasCodec *pThis)
	True if this codec trims (DASENC_TRIM).
DAS_API void	DasCodec_postBlit (DasCodec *pThis, DasAry *pAry)
	Fix array pointer after a DasCodec memory copy.
DAS_API DasErrCode	DasCodec_setIdxTerms (DasCodec *pThis, ubyte nLevels, const char *sLevels)
	Attach the per-index run terminators after codec creation.
DAS_API bool	DasCodec_isReader (const DasCodec *pThis)
	Is this codec setup and a reader from external buffers or a write to them ?
DAS_API bool	DasCodec_isText (const DasCodec *pThis)
	Does this codec emit (or read) text, i.e.
DAS_API int	DasCodec_decode (DasCodec *pThis, const ubyte *pBuf, int nBufLen, int nExpect, int *pValsRead)
	Read values from a simple buffer into an array.
DAS_API int	DasCodec_raggedIndices (const DasCodec *pThis, int *aRagIdx)
	Locate the external ragged indices this codec's runs close.
DAS_API int	DasCodec_decodeRuns (DasCodec *pThis, const ubyte *pBuf, int nBufLen, bool bLastVar, int *pValsRead)
	Read terminator-bounded (idxTerm) ragged runs from a buffer.
DAS_API int	DasCodec_encodeRuns (DasCodec *pThis, DasBuf *pBuf, ptrdiff_t iRec)
	Write one record's terminator-bounded (idxTerm) ragged run to a buffer.
DAS_API void	DasCodec_deInit (DasCodec *pThis)
	Release the reference count on the array given to this encoder/decoder.
DAS_API bool	das_cred_init (das_credential *pCred, const char *sServer, const char *sRealm, const char *sDataset, const char *sHash)
	Initialize a credential to be cached in the credentials manager.

Detailed Description

Classes and functions reading and writing byte streams.

Typedef Documentation

das_prompt

typedef bool(* das_prompt) (const char *sServer, const char *sRealm, const char *sDataset, const char *sMessage, char *sUser, char *sPassword)

Function signature for swapping out the user-prompt for credentials acquisition.

Parameters

sServer	The server name
sRealm	The authorization realm on this server, can be same as the dataset
sDataset	The name of the dataset on this server
sMessage	An additional message that may be supplied, such as "The user name cannot contain a colon, ':', character"
sUser	a pointer to 128 bytes of storage to hold the username
sPassword	a pointer to 128 bytes of storage to hold the password

Returns

true if the user entered a user name and password (even empty ones) and false if the prompt was canceled.

Function Documentation

DasCodec_encode()

DAS_API int DasCodec_encode	(	DasCodec *	pThis,
		DasBuf *	pBuf,
		int	nDim,
		ptrdiff_t *	pLoc,
		int	nExpect,
		uint32_t	uFlags
	)

Write values from an array into a buffer, does not change the array.

The goal of this function is to emitt all data from continuous range of indexes starting at a given point. Examples of setting the start location:

nDim=0, pLoc=NULL as DIM0 => Emitt the entire array

nDim=1, pLoc={I} as DIM1_AT(I) => Emit all data for one increment of the highest index

nDim=2, pLoc={I,J} as DIM2_AT(I,J) => Emit all data for one increment of the the next highest index.

To write all data for an array set: nDim = 0, pLoc = NULL (aka use DIM0 )

Parameters

pThis	The codec structure
pBuf	The output receiver
nDim	Part of the start location specification, see description above
pLoc	Part of the start location specification, see description above
nExpect	The number of items expected to be written. If -1 then the output is variable length. In the case of text items this is the number of strings, not the number of total characters
uFlags	that affect the output. The following are defined, mostly for text output:

DASENC_PKTLAST - This is the last item output for for a packet Add a new line character after it if text.

DASENC_INHDR - Encoding is being performed for a header, so don't emit too many items in a single row.

Returns

The number of values written or a negative ERR code if a data conversion error occurred.

das_ssl_getErr()

DAS_API char * das_ssl_getErr	(	const void *	vpSsl,
		int	nRet
	)

Get a new string allocated on the heap explaining an SSL error or NULL in nRet == 0.

To prevent memory leaks, caller must free string if return is NON null.

DasCodec_init()

DAS_API DasErrCode DasCodec_init	(	bool	bRead,
		DasCodec *	pThis,
		DasAry *	pAry,
		const char *	sSemantic,
		const char *	sEncType,
		int16_t	uSzEach,
		ubyte	cSep,
		das_units	epoch,
		const char *	sOutFmt
	)

Initialize a serial buffer decoder/encoder.

Parameters

bRead	if set to DASENC_READ, perform checks for value reading codecs if set to DASENC_WRITE, perform checks for value writing codecs
pThis	A pointer to the memory area to initialize
pAry	A pointer to the array which either receive or supply values. Values will be encoded so that they match the value type of the array.

Warning

If the basic parameters of this array, such as it's value type or rank are changed, then DasCodec_init() must be re-called.

Parameters

sSemantic	The purpose of the data to store in the buffer, should be one of 'bool','int','real','datatime','string'. This determines the kinds of calculations that may be performed on the data once in memory.
sEncType	The basic encoding type of data in the buffer, one of: byte : 8-bit signed integer ubyte : 8-bit un-signed integer BEint : A signed integer 2+ bytes long, most significant byte first BEuint : An un-signed integer 2+ bytes long MSB first LEint : Little-endian version of BEint LEuint : Little-endian version of BEuint BEreal : An IEEE-754 floating point value, MSB first LEreal : An IEEE-754 floating point value, LSB first utf8 : A string of text bytes
nSzEach	the number of bytes in an item. For variable length items (which is common with the utf8 encoding) use DASENC_ITEM_SEP, or DASENC_ITEM_LEN.
cSep	A single byte used to mark the end of a byte sequence for string data. By default any space character marks the end of a string. Use 0 to ignore.
epoch	If time data needs to be decoded from UTC strings an epoch will be needed. Otherwise this field can be NULL
sOutFmt	a printf style format string, may be NULL for input only codecs, or to have the initializer set a default output format string

Typical strings for general data values would be: '%9.2e', '%+13.6e'. In general strings such as '%13.3f' should not be used as these aren't guaranteed to have a fix output width and your value strings may be truncated.

Returns

DAS_OKAY if an decoder/encoder for can be created for the given arguments, an error code otherwise.

Note

For 'string' semantic data where the last index in the array is ragged DasAry_markEnd() will be called after each string is read. Otherwise, no string larger then the last index will be written and zeros will be appended to fill out the last index when reading data.

DasCodec_update()

DAS_API DasErrCode DasCodec_update	(	bool	bRead,
		DasCodec *	pThis,
		const char *	sEncType,
		int16_t	uSzEach,
		ubyte	cSep,
		das_units	epoch,
		const char *	sOutFmt
	)

Update external aspects of a serial buffer decoder/encoder.

Other then three mandatory items, only properties you want to change need to be non-null, or not-flag values.

Parameters

bRead	if set to DASENC_READ, perform checks for value reading codecs if set to DASENC_WRITE, perform checks for value writing codecs
pThis	A pointer to the memory area to initialize
sEncType	The basic encoding type of data in the buffer, one of: byte : 8-bit signed integer ubyte : 8-bit un-signed integer BEint : A signed integer 2+ bytes long, most significant byte first BEuint : An un-signed integer 2+ bytes long MSB first LEint : Little-endian version of BEint LEuint : Little-endian version of BEuint BEreal : An IEEE-754 floating point value, MSB first LEreal : An IEEE-754 floating point value, LSB first utf8 : A string of text bytes or use NULL to leave unchanged
nSzEach	the number of bytes in an item. Use 0 t leave unchanged.
cSep	A single byte used to mark the end of a byte sequence for string data. Use 0 to leave unchanged.
epoch	If time data needs to be decoded from UTC strings an epoch will be needed. Use NULL to leave unchanged
sOutFmt	a printf style format string, may be NULL to leave unchanged.

Returns

DAS_OKAY if an decoder/encoder for can be created for the given arguments, an error code otherwise.

Note

For 'string' semantic data where the last index in the array is ragged DasAry_markEnd() will be called after each string is read. Otherwise, no string larger then the last index will be written and zeros will be appended to fill out the last index when reading data.

DasCodec_setTrim()

DAS_API void DasCodec_setTrim	(	DasCodec *	pThis,
		bool	bTrim
	)

Enable/disable ltrim+rtrim of decoded values (var-width utf8, default on).

Distinct from eatSpace: trim keeps internal spaces, only stripping surrounding pad. Wired to <packet trim="...">. A space-only string collapses to just "" which is a null string and is completely legal.

Read-side only.

DasCodec_isTrim()

DAS_API bool DasCodec_isTrim

(

const DasCodec *

pThis

)

True if this codec trims (DASENC_TRIM).

Lets the writer re-emit a non-default trim="false" so surrounding whitespace survives a round-trip.

DasCodec_postBlit()

DAS_API void DasCodec_postBlit	(	DasCodec *	pThis,
		DasAry *	pAry
	)

Fix array pointer after a DasCodec memory copy.

Parameters

pThis	A pointer to the new memory area filled via memcpy()
pAry	The new array to associate with this codec

DasCodec_setIdxTerms()

DAS_API DasErrCode DasCodec_setIdxTerms	(	DasCodec *	pThis,
		ubyte	nLevels,
		const char *	sLevels
	)

Attach the per-index run terminators after codec creation.

The value terminator (valTerm) is set when the codec is created and lives at sSepSet[0]; this call fills sSepSet[1..] outer-most first and updates nSep. The list is all-or-nothing: either one terminator per external RAGGED index, or one per EVERY external index down to the inner-most ragged one (the decorated form, where fixed extents inside the run structure get a formally redundant terminator for readability).

Since internal/external is a DasVar concept and not an encoding concept the caller has to set this up.

Parameters

pThis	the codec to configure
nLevels	the number of run-terminator levels (1..VARIDX_MAX-1)
sLevels	the level bytes, outer-most first, nLevels long

Returns

DAS_OKAY, or a das error code on a bad or colliding terminator

DasCodec_isText()

DAS_API bool DasCodec_isText

(

const DasCodec *

pThis

)

Does this codec emit (or read) text, i.e.

does it use utf8 terminator framing? True for encoding="utf8" and for binary values re-encoded as text; false for intrinsic binary and for {N}-framed blob/base64. The ragged run terminators (idxTerm) apply only when this is true.

DasCodec_decode()

DAS_API int DasCodec_decode	(	DasCodec *	pThis,
		const ubyte *	pBuf,
		int	nBufLen,
		int	nExpect,
		int *	pValsRead
	)

Read values from a simple buffer into an array.

Unlike the old das2 version, this encoder doesn't have a built-in number of values it will always expect to read. If no pre-determined number of values is given in nExpect, then it will read until the buffer is exhausted.

To control the number of bytes read control nBufLen

Parameters

pThis	An encoder. The pointer isn't constant because the encoder may have to allocate some memory for long, variable length text values, so internal state may change.
pBuf	A pointer to the memory to read
nBufLen	The length of the buffer parse into the array. Note that even for string data the function tries to read nLen bytes. Null values do not terminate parsing but do indicate the end of an individual utf-8 encoded item.
nExpect	The number of values to try and read. Reading less then this does not trigger an error return. If the caller considers reading less values then expect to be an error, compare *pValsRead with the number provided for nExpect. If any number of values can be read, set this to -1.
pValsRead	A pointer to a location to hold the number of values read or NULL. If NULL, the number of values read will not be returned

Returns

the number of unread bytes or a negative ERR code if a data conversion error occurred.

DasCodec_raggedIndices()

DAS_API int DasCodec_raggedIndices	(	const DasCodec *	pThis,
		int *	aRagIdx
	)

Locate the external ragged indices this codec's runs close.

Fills aRagIdx[0..N-1] (N = nExtRagged) with the position of each external ragged index ('j', 'k', ...) in the backing array's index order, outer-most first.

Parameters

pThis	the codec; nExtRagged must already be set
aRagIdx	receives the index positions; must hold VARIDX_MAX entries

Returns

the number of ragged levels (>= 1), or a negative das error code

DasCodec_decodeRuns()

DAS_API int DasCodec_decodeRuns	(	DasCodec *	pThis,
		const ubyte *	pBuf,
		int	nBufLen,
		bool	bLastVar,
		int *	pValsRead
	)

Read terminator-bounded (idxTerm) ragged runs from a buffer.

The counterpart of DasCodec_decode for variable-count utf8 runs. Since the run lengths denoted by values and index terminator characters the are unknowable up front. The codec consumes values until the declared run terminators (sSepSet[1..], set via DasCodec_setIdxTerms) close every level, calling DasAry_markEnd itself as each level closes.

A higher-level terminator also closes open lower levels (the collapsed form). The packet edge acts as the stream-index terminator: it closes all open runs, but only the packet's last variable may lean on it.

Parameters

pThis	a text codec with at least one idxTerm level attached
pBuf	the read point, positioned at the start of this codec's runs
nBufLen	bytes remaining in the packet
bLastVar	true if this is the last variable in the packet, making the packet edge a legal run close
pValsRead	if non-NULL, receives the number of values read

Returns

the number of unread bytes, or a negative das error code

DasCodec_encodeRuns()

DAS_API int DasCodec_encodeRuns	(	DasCodec *	pThis,
		DasBuf *	pBuf,
		ptrdiff_t	iRec
	)

Write one record's terminator-bounded (idxTerm) ragged run to a buffer.

The write mirror of DasCodec_decodeRuns: emits every run under record iRec with the full declared terminator stack at every boundary, including against the packet edge (collapsed forms are read, never written).

Parameters

pThis	a text codec with at least one idxTerm level attached
pBuf	the output receiver
iRec	the record (highest array index) to emit

Returns

the number of values written, or a negative das error code

das_cred_init()

DAS_API bool das_cred_init	(	das_credential *	pCred,
		const char *	sServer,
		const char *	sRealm,
		const char *	sDataset,
		const char *	sHash
	)

Initialize a credential to be cached in the credentials manager.

Parameters

pCred	A pointer to a das_credentials structure
sServer	The name of the server, ex: 'jupiter.physics.uiowa.edu'
sRealm	The authentication realm. This is provided in the dsdf files under the securityRealm keyword.
sDataset	The dataset, ex: 'Juno/WAV/Survey' The dataset is typically determined by the http module by URL inspection. If this credentials manager is used for a general URL then the http module will not specify the the dataset. To match those sites, use NULL here.
sHash	The hash value. Currently the library only supports HTTP Basic Authentication hashes. i.e. a USERNAME:PASSWORD string that has been base64 encoded.