source/dscore/src/siQuery.h File Reference

Header to siQuery module - functions for managing SI queries. More...

#include "clDsmSystem.h"
#include "linkList.h"

Go to the source code of this file.

Data Structures
struct	SiQuery_t
Defines
#define	SI_QUERY_MAGIC   0xC537D89E
Typedefs
typedef struct SiQuery_t *	pSiQuery_t
Enumerations
enum	SiQueryState_t {   SIQS_INITIAL = 0, SIQS_PENDING, SIQS_COMPLETED, SIQS_ABORTED,   SIQS_EXPIRED }
Functions
clDsmErr_t	siQueryStart (pclDsmInstData_t idp, pclDsmSIQuery_t pQueryData, void *queryTarget, clDsmSIQueryResult_t *pResult)
	Starts an SI Query. First tests if we have already made this query and the results are stored or still pending. Otherwise tries SI query callback. If results are not synchronously returned, stores state of query ready for when they are asynchronously returned (via clDsmProcessSiQueryEvent). NB. If start returns results SYNCHRONOUSLY then siQueryStop must not be called.
void	siQueryAbortPending (pclDsmInstData_t idp, MemHandle *phPendingSiQueryRef)
	Aborts the specified SI Query before completion. Stops/destroys duplicate queries. For original queries or duplicate queries that have expired parents (and no further duplicates) calls stop SI Query callback on relevant query.
void	siQueryStop (pclDsmInstData_t idp, MemHandle *phSiQueryRef)
	Stops the specified SI Query. Removes from any lists it is in and destroys associated memory object. NB. If siQueryStart returned results SYNCHRONOUSLY then this must not be called.
clDsmErr_t	siQueryProcessResult (pclDsmInstData_t idp, MemHandle hSiQueryRef, pclDsmSIQueryResult_t pResult)
	Processes and stops the specified SI Query.

---

Detailed Description

Header to siQuery module - functions for managing SI queries.

Date:

07/05/2002

Author:

N Kirkland

---

Function Documentation

void siQueryAbortPending	(	pclDsmInstData_t	idp,
		MemHandle *	phPendingSiQueryRef
	)

Aborts the specified SI Query before completion. Stops/destroys duplicate queries. For original queries or duplicate queries that have expired parents (and no further duplicates) calls stop SI Query callback on relevant query.

Parameters:

idp	Pointer to instance data.
phPendingSiQueryRef	Pointer to handle of query to abort.

Returns:

clDsmErr_t siQueryProcessResult	(	pclDsmInstData_t	idp,
		MemHandle	hSiQueryRef,
		pclDsmSIQueryResult_t	pResult
	)

Processes and stops the specified SI Query.

Parameters:

idp	Pointer to instance data.
hSiQueryRef	Refererence for this query (value supplied at start time).
status	Status of query results.
pResult	Pointer to results of query (if successful).

Returns:

CLDSM_OK (0) The process SI query event was executed with no problems. CLDSM_ERR_INVALID_SIQUERY_STATUS Supplied status value is invalid here. CLDSM_ERR_SYSTEM_ADD_SECTION_FILTER, Problem with add section filter callback.

clDsmErr_t siQueryStart	(	pclDsmInstData_t	idp,
		pclDsmSIQuery_t	pQueryData,
		void *	queryTarget,
		clDsmSIQueryResult_t *	pResult
	)

Starts an SI Query. First tests if we have already made this query and the results are stored or still pending. Otherwise tries SI query callback. If results are not synchronously returned, stores state of query ready for when they are asynchronously returned (via clDsmProcessSiQueryEvent). NB. If start returns results SYNCHRONOUSLY then siQueryStop must not be called.

Parameters:

idp	Pointer to instance data.
pQueryData	Pointer to structure containing query details.
queryTarget	Handle to target of query (ie. object that needs query results - eg. carousel or section filter).
pResult	Results of query if synchronously returned.

Returns:

CLDSM_OK Everything hunkydory CLDSM_ERR_SI_QUERY_FAILED Synchronous SI query failed to determine requested information CLDSM_MEM_HEAP_FULL Internal memory manager heap full (treat as internal error)

void siQueryStop	(	pclDsmInstData_t	idp,
		MemHandle *	phSiQueryRef
	)

Stops the specified SI Query. Removes from any lists it is in and destroys associated memory object. NB. If siQueryStart returned results SYNCHRONOUSLY then this must not be called.

Parameters:

idp	Pointer to instance data.
phSiQueryRef	Pointer to handle of query to stop (nulled after call).

Returns: