next up previous 264
Next: astChannelData - Return a pointer to user-supplied data stored with a Channel
Up: AST Function Descriptions
Previous: astBox - Create a Box


astChannel - Create a Channel

Description:
This function creates a new Channel and optionally initialises its attributes.

A Channel implements low-level input/output for the AST library. Writing an Object to a Channel (using astWrite) will generate a textual representation of that Object, and reading from a Channel (using astRead) will create a new Object from its textual representation.

Normally, when you use a Channel, you should provide "source" and "sink" functions which connect it to an external data store by reading and writing the resulting text. By default, however, a Channel will read from standard input and write to standard output.

Synopsis:
AstChannel $*$astChannel( const char $*$($*$ source)( void ), void ($*$ sink)( const char $*$ ), const char $*$options, ... )
Parameters:
source
Pointer to a source function that takes no arguments and returns a pointer to a null-terminated string. This function will be used by the Channel to obtain lines of input text. On each invocation, it should return a pointer to the next input line read from some external data store, and a NULL pointer when there are no more lines to read.

If "source" is NULL, the Channel will read from standard input instead.

sink
Pointer to a sink function that takes a pointer to a null-terminated string as an argument and returns void. This function will be used by the Channel to deliver lines of output text. On each invocation, it should deliver the contents of the string supplied to some external data store.

If "sink" is NULL, the Channel will write to standard output instead.

options
Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new Channel. The syntax used is identical to that for the astSet function and may include "printf" format specifiers identified by "%" symbols in the normal way.
...
If the "options" string contains "%" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C "printf" function).
Returned Value:
astChannel()
A pointer to the new Channel.
Notes:
  • Application code can pass arbitrary data (such as file descriptors, etc) to source and sink functions using the astPutChannelData function. The source or sink function should use the astChannelData macro to retrieve this data.

  • A null Object pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason.


next up previous 264
Next: astChannelData - Return a pointer to user-supplied data stored with a Channel
Up: AST Function Descriptions
Previous: astBox - Create a Box

AST A Library for Handling World Coordinate Systems in Astronomy
Starlink User Note 211
R.F. Warren-Smith & D.S. Berry
24th May 2011
E-mail:ussc@star.rl.ac.uk

Copyright (C) 2009 Science \& Technology Facilities Council