Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members  

newssvcdec.h File Reference


Detailed Description

Journaline(R) news service decoder interface.

techidee GmbH

Projekt: NewsBox

Autor: Thomas Fruehwald

Compiler: gcc

Modul: news service decoder

Creation date: 2003-08-02

Last modified: 2004-02-16 (rbr)

The Journaline(R) news service decoder will accept Journaline(R) objects conforming to the news service "Journaline(R)" specification and store them (subject to specified memory limits) for later retrieval by a Journaline(R) application.

To use it, call createDec to create an instance, putData to put Journaline(R) objects into the decoder and in the end, use deleteDec to destroy the instance.

To make use of the watch functionality for monitoring object availability information, you must implement the object availability callback and pass it to createDec.

Attention:
The Journaline(R) news service decoder is not thread safe.

Go to the source code of this file.

Compounds

struct  NEWS_SVC_DEC_obj_availability_t
 object availability type More...


Typedefs

typedef const void * NEWS_SVC_DEC_decoder_t
 news service decoder instance type

typedef void( NEWS_SVC_DEC_cb )(unsigned long number_of_elements, NEWS_SVC_DEC_obj_availability_t *chg_list, void *arg)
 object availability callback function


Enumerations

enum  NEWS_SVC_DEC_obj_availability_status_t { NEWS_SVC_DEC_OBJ_NOT_YET_AVAILABLE, NEWS_SVC_DEC_OBJ_REMOVED, NEWS_SVC_DEC_OBJ_RECEIVED, NEWS_SVC_DEC_OBJ_UPDATED }
 object availability status type More...


Functions

NEWS_SVC_DEC_decoder_t NEWS_SVC_DEC_createDec (NEWS_SVC_DEC_cb update, unsigned long max_memory, unsigned long *max_objects, unsigned long extended_header_len, void *arg)
 Create a news service decoder instance.

void NEWS_SVC_DEC_deleteDec (NEWS_SVC_DEC_decoder_t decoder)
 Delete a news service decoder instance.

int NEWS_SVC_DEC_get_news_object (NEWS_SVC_DEC_decoder_t decoder, unsigned short object_id, unsigned long *extended_header_len, unsigned long *len, unsigned char *nml)
 Get a news object by id.

int NEWS_SVC_DEC_get_object_availability (NEWS_SVC_DEC_decoder_t decoder, unsigned long number_of_elements, NEWS_SVC_DEC_obj_availability_t *query_list)
 Query the availability of objects.

unsigned long NEWS_SVC_DEC_putData (NEWS_SVC_DEC_decoder_t decoder, const unsigned long len, const unsigned char *buf)
 Put data into news decoder.

int NEWS_SVC_DEC_watch_objects (NEWS_SVC_DEC_decoder_t decoder, unsigned long number_of_elements, NEWS_SVC_DEC_obj_availability_t *watch_list)
 Set a watch on the specified objects.

int NEWS_SVC_DEC_keep_in_cache (NEWS_SVC_DEC_decoder_t decoder, unsigned long number_of_elements, unsigned short *object_ids)
 Set ids of objects to be kept in cache.


Typedef Documentation

typedef void( NEWS_SVC_DEC_cb)( unsigned long number_of_elements, NEWS_SVC_DEC_obj_availability_t *chg_list, void *arg )
 

object availability callback function

The object availability callback function will be called when the object availability status of one or more of the objects in the watch list changes.

Parameters:
number_of_elements  number of elements in change list
chg_list  change list
arg  user specified data pointer (as specified in createDec)

typedef const void* NEWS_SVC_DEC_decoder_t
 

news service decoder instance type


Enumeration Type Documentation

enum NEWS_SVC_DEC_obj_availability_status_t
 

object availability status type

Enumeration values:
NEWS_SVC_DEC_OBJ_NOT_YET_AVAILABLE  object is not yet available
NEWS_SVC_DEC_OBJ_REMOVED  object has been removed because of memory restrictions
NEWS_SVC_DEC_OBJ_RECEIVED  object has been received
NEWS_SVC_DEC_OBJ_UPDATED  update of already received object


Function Documentation

NEWS_SVC_DEC_decoder_t NEWS_SVC_DEC_createDec NEWS_SVC_DEC_cb    update,
unsigned long    max_memory,
unsigned long *    max_objects,
unsigned long    extended_header_len,
void *    arg
 

Create a news service decoder instance.

call this before anything else

Parameters:
update  callback function (may be 0 to indicate watching is not used)
max_memory  value in bytes for the news-service the value is truncated to the nearest multiple of the (internal) news object representation approx. 2200 bytes (2044 bytes is the longest nml)
max_objects  maximum number of objects. if 0 the whole max_news_service_memory is used. otherwise the sharper restriction limits the object count (e.g. max_news_service_memory -> 10 objects, max_object_count=5 -> 5 objects)
extended_header_len  length of NML extended header in bytes (signalled in SDC)
arg  user specified data pointer (will only be passed to callback)
Returns :
created news service decoder instance
Return values:
0  on failure

void NEWS_SVC_DEC_deleteDec NEWS_SVC_DEC_decoder_t    decoder
 

Delete a news service decoder instance.

call this at shutdown time

Parameters:
decoder  news service decoder instance (as obtained by NEWS_SVC_DEC_createDec)
Return values:
0  on failure
1  on success

int NEWS_SVC_DEC_get_news_object NEWS_SVC_DEC_decoder_t    decoder,
unsigned short    object_id,
unsigned long *    extended_header_len,
unsigned long *    len,
unsigned char *    nml
 

Get a news object by id.

The object with id object_id will be written to nml and len will be set to its actual length in bytes (at most 2044).

Parameters:
decoder  news service decoder instance (as obtained by NEWS_SVC_DEC_createDec)
object_id  NML object id (0000-FFFF)
extended_header_len  (out) length in bytes of extended header field of this news service (as signalled in SDC)
len  (out) length in bytes of NML object
nml  (out) the complete NML object (including NML header)
Return values:
0  on failure

int NEWS_SVC_DEC_get_object_availability NEWS_SVC_DEC_decoder_t    decoder,
unsigned long    number_of_elements,
NEWS_SVC_DEC_obj_availability_t   query_list
 

Query the availability of objects.

Specify a list of objects (only the object ids have to be filled in) you want to query in query_list.

on return the status field of query_list will be set.

Parameters:
decoder  news service decoder instance (as obtained by NEWS_SVC_DEC_createDec)
number_of_elements  length of SVCMGR_UI_object_availability_t array
query_list  (inout) list of objects for which the status is queried
Return values:
0  on failure

int NEWS_SVC_DEC_keep_in_cache NEWS_SVC_DEC_decoder_t    decoder,
unsigned long    number_of_elements,
unsigned short *    object_ids
 

Set ids of objects to be kept in cache.

Tell the memory management that the listed elements should be kept in memory (if possible).

Candidates for keeping in memory are (in order of importance):

  1. currently viewed object
  2. parents of currently viewed object
  3. children of currently viewed (menu) object
  4. "favorite" objects
Note:
Every call to this function overwrites the last keep-in-memory list.
Parameters:
decoder  news service decoder instance (as obtained by NEWS_SVC_DEC_createDec)
number_of_elements  length of object_id array
object_ids  list of ids of objects which should be kept in cache
Return values:
0  on failure

unsigned long NEWS_SVC_DEC_putData NEWS_SVC_DEC_decoder_t    decoder,
const unsigned long    len,
const unsigned char *    buf
 

Put data into news decoder.

The input for the news decoder consists of one complete Journaline(R) object.

Parameters:
decoder  news service decoder instance (as obtained by NEWS_SVC_DEC_createDec)
len  length in bytes of Journaline(R) object
buf  Journaline(R) object
Return values:
0  on failure

int NEWS_SVC_DEC_watch_objects NEWS_SVC_DEC_decoder_t    decoder,
unsigned long    number_of_elements,
NEWS_SVC_DEC_obj_availability_t   watch_list
 

Set a watch on the specified objects.

When the status of an object with an id that is being watched on changes, a callback is done. To avoid nested upcalls the status at the calling time is returned in the watch_list's status field.

Note:
Every call to this function overwrites the last watch list.
Parameters:
number_of_elements  length of SVCMGR_UI_object_availability_t array
decoder  news service decoder instance (as obtained by NEWS_SVC_DEC_createDec)
watch_list  (inout) list of objects for which a watch is set.
On input, the object_id field has to be specified.

On output, the status field will be filled.

Return values:
0  on failure


Generated on Thu Mar 18 13:10:33 2004 for journaline_demo by doxygen1.2.17