Faspstream Manager C/C++ API  1.0
A C and C++ language interface to basic streaming over the fasp protocol
fasp_stream.h File Reference
#include <stdlib.h>

Go to the source code of this file.

Macros

#define FASPSTREAM_C_API
 

Typedefs

typedef struct fasp_stream fasp_stream_t
 

Functions

FASPSTREAM_C_API fasp_stream_tfasp_stream_create ()
 
FASPSTREAM_C_API int fasp_stream_close (fasp_stream_t *ctx)
 
FASPSTREAM_C_API int fasp_stream_destroy (fasp_stream_t *ctx)
 
FASPSTREAM_C_API int fasp_stream_eof (fasp_stream_t *ctx)
 
FASPSTREAM_C_API int fasp_stream_opts_list (const char **options, const char **data_types)
 
FASPSTREAM_C_API int fasp_stream_opts_set (fasp_stream_t *ctx, const char *option, const char *value)
 
FASPSTREAM_C_API const char * fasp_stream_opts_get (fasp_stream_t *ctx, const char *option)
 
FASPSTREAM_C_API void fasp_stream_set_path (fasp_stream_t *ctx, const char *path)
 
FASPSTREAM_C_API int fasp_stream_start_listening (fasp_stream_t *ctx, const char *port)
 
FASPSTREAM_C_API int fasp_stream_connect (fasp_stream_t *ctx, const char *host, const char *port)
 
FASPSTREAM_C_API size_t fasp_stream_read (fasp_stream_t *ctx, char *buf, size_t len)
 
FASPSTREAM_C_API size_t fasp_stream_write (fasp_stream_t *ctx, const char *buf, size_t len)
 

Macro Definition Documentation

#define FASPSTREAM_C_API

Typedef Documentation

typedef struct fasp_stream fasp_stream_t

Function Documentation

FASPSTREAM_C_API int fasp_stream_close ( fasp_stream_t ctx)

Closes the fasp stream (and flushes any remaining data if sending). This will also terminate the child faspstream process.

Parameters
ctxfasp stream context
Returns
integer representing success (zero) or failure (non-zero)
FASPSTREAM_C_API int fasp_stream_connect ( fasp_stream_t ctx,
const char *  host,
const char *  port 
)

Starts the faspstream child process which will attempt to create an outgoing connection (this is a blocking function). Returns 0 on success, non-zero otherwise. After connecting, data may be sent (via fasp3_stream_write()), but it must not be received (via fasp3_stream_read()).

Parameters
ctxfasp stream context
hoststring name or IP address of remote fasp stream host
portstring representation of TCP port for connection
Returns
integer representing success (zero) or failure (non-zero)
FASPSTREAM_C_API fasp_stream_t* fasp_stream_create ( )

Constructs a new context, returns NULL on error.

Returns
pointer to fasp stream context (for subsequent calls)
FASPSTREAM_C_API int fasp_stream_destroy ( fasp_stream_t ctx)
FASPSTREAM_C_API int fasp_stream_eof ( fasp_stream_t ctx)
FASPSTREAM_C_API const char* fasp_stream_opts_get ( fasp_stream_t ctx,
const char *  option 
)
FASPSTREAM_C_API int fasp_stream_opts_list ( const char **  options,
const char **  data_types 
)

Returns the number of options available. If options is not NULL, its size must be equal to the return value of the function, and it is populated with a list of C-style strings listing the names of all the options. Likewise for data_types, though it is filled with a description of the values that the corresponding options take. That is, data_types[i] describes the type of values options[i] takes.

Parameters
optionslist of array strings (out parameter) (may be NULL, in which case it is ignored and not used)
data_typeslist of corresponding data types (out parameter) (may be NULL, in which case it is ignored and not used)
Returns
integer representing number of options this API offers
1 // Find out the number of options
2 int num_opts = fasp3_stream_opts_list(NULL, NULL);
3 
4 // Allocate memory for storage
5 const char **options = malloc(num_opts * sizeof(const char*));
6 const char **data_types = malloc(num_opts * sizeof(const char*));
7 
8 // Fill the arrays
9 fasp3_stream_opts_list(options, data_types);
10 
11 // Print out the options
12 for (int i = 0; i < num_opts; ++i) {
13  printf("option name: %s option value type: %s\n", options[i], data_types[i]);
14 }
15 
16 // Clean up memory
17 free(options);
18 free(data_types);
FASPSTREAM_C_API int fasp_stream_opts_set ( fasp_stream_t ctx,
const char *  option,
const char *  value 
)

Sets a fasp option by name. For a list of valid options and types of values, see fasp3_stream_opts_list().

Parameters
ctxfasp stream context
optionread-only name of option to set
valueread-only value to which named option will be set
Returns
integer representing success (zero) or failure (non-zero)
FASPSTREAM_C_API size_t fasp_stream_read ( fasp_stream_t ctx,
char *  buf,
size_t  len 
)

Reads available data from a previously listening connection. Returns the number of bytes read into buf, which is up to len bytes. This is a non-blocking function, and may return 0. Use fasp3_stream_eof() to determine if the end of the stream has been reached.

Parameters
ctxfasp stream context
bufpointer to buffer containing bytes read (out parameter)
lennumber of bytes read into buf
Returns
integer representing actual number of bytes read from the stream
FASPSTREAM_C_API void fasp_stream_set_path ( fasp_stream_t ctx,
const char *  path 
)
FASPSTREAM_C_API int fasp_stream_start_listening ( fasp_stream_t ctx,
const char *  port 
)

Starts a faspstream sub-process which will wait for an incoming stream connection (NOTE: unlike "accept()", this is a NON-blocking function). Returns 0 on success staring process, non-zero otherwise. After this call, you may call fasp_stream_read(), which IS a blocking call that will wait for the first bytes of the stream to be received. fasp_stream_write() must not be called after this function.

Parameters
ctxfasp stream context
portstring representation of numerical TCP port on which to listen for incoming connections
Returns
integer representing success (zero) or failure (non-zero)
FASPSTREAM_C_API size_t fasp_stream_write ( fasp_stream_t ctx,
const char *  buf,
size_t  len 
)

Writes up to len bytes of data from buf to the connected stream. Returns the number of bytes written. This is a non-blocking function, and may return 0.

Parameters
ctxfasp stream context
bufbuffer to write out to remote fasp stream
lenlength of buffer to be written
Returns
integer representing actual number of bytes written to the stream