#include <das2/node.h>

Detailed Description

Base type for das2 catalog nodes.

Public Member Functions
DasNode *	new_RootNode (const char sPathUri, DasCredMngr pMgr, const char *sAgent)
	Create a new root catalog node via a path URI. More...

DasNode *	new_RootNode_url (const char sUrl, const char sPathUri, DasCredMngr pMgr, const char sAgent)
	Create a new root catalog node via direct URL. More...

DasNode *	DasNode_subNode (DasNode pThis, const char sRelPath, DasCredMngr pMgr, const char sAgent)
	Get a das2 catalog node contained item. More...

bool	DasNode_isCatalog (const DasNode *pNode)
	Returns true this node can contain sub nodes.

bool	DasNode_isStreamSrc (const DasNode *pNode)
	Determine if this node defines a das2 stream source.

bool	DasNode_isSpaseRec (const DasNode *pNode)
	Determine if this node is a SPASE record.

bool	DasNode_isSpdfCat (const DasNode *pNode)
	Determine if this node is an SPDF catalog.

const char *	DasNode_pathUri (const DasNode *pThis)
	Get the path URI for this catalog node. More...

const char *	DasNode_srcUrl (const DasNode *pThis)
	Get the location from which this catalog node was read. More...

das_node_type_e	DasNode_type (const DasNode *pThis)
	Get the type of node This is a more specific question than the 'is' functions below, which should probably be used instead so that application code can work in a "duck-typing" manner. More...

const char *	DasNode_name (const DasNode *pThis)
	Get the node title. More...

const char *	DasNode_title (const DasNode *pThis)
	Get the node short description, if provided.

const DasJdo *	DasNode_getJdo (const DasNode pThis, const char sFragment)
	Get a JSON document object at a fragment location in a node. More...

const DasJdo *	DasNode_getJdoType (const DasNode pThis, enum das_json_type_e, const char sFragment)
	Get a JSON document object of a particular type at a fragment location. More...

void	del_RootNode (DasNode *pNode)
	Delete a root node freeing it's memory. More...

Member Function Documentation

DasNode * new_RootNode	(	const char *	sPathUri,
		DasCredMngr *	pMgr,
		const char *	sAgent
	)

Create a new root catalog node via a path URI.

Get a catalog node that is not attached to any parent nodes. If the node acquired is a container type such as Root, Scheme, or Catalog then it can be used to aquire further nodes.

This function consults the distributed das2 catalog to find and load nodes. See new_RootNode_url() for a version that only loads a specified URL.

DasNode* pRoot = NULL;
// Get the das2 site root catalog node
pRoot = new_RootNode(D2URI_DAS_SITE_ROOT, NULL, NULL, NULL);
// Get the U. Iowa site catalog top node
pRoot = new_RootNode(D2URI_DAS_SITE_ROOT "/uiowa", NULL, NULL);

Parameters

sPathUri	Retrieve a catalog node given a global path URI. This a location from the top of the federated catalog system, not a file system or web path.
sAgent	The user agent string you wish to send to the server. If NULL then the string "libdas2/2.3" is sent.
pMgr	A credentials manager object to consult if a password is requested. May be set to NULL to indicate that only public items may be requested. Usually this is not needed as most catalog entries are public though the data sources they describe may not be.

Returns: A new DasNode object allocated on the heap, or NULL if object resolution failed. Calling del_RootNode() for the returned pointer will delete all sub-nodes from memory as well.

DasNode * new_RootNode_url	(	const char *	sUrl,
		const char *	sPathUri,
		DasCredMngr *	pMgr,
		const char *	sAgent
	)

Create a new root catalog node via direct URL.

Get a catalog node that is not attached to any parent nodes. If the node acquired is a container type such as Root, Scheme, or Catalog then it can be used to aquire further nodes.

There are two basic methods of node acquisition, set a path URI and let the library find the node using the built-in global catalog location, or provide an explicit URL.

DasNode* pRoot = NULL;
  
// Get a standalone local Voyager catalog root
pRoot = new_RootNode(NULL, "http://my.site.gov/test/local_vgr.json", NULL, NULL);
// Get a standalone data source description for Voyager PLS data
pRoot = new_RootNode(NULL, "http://my.site.gov/test/local_vgr/pls.json", NULL, NULL);

Parameters

sUrl	Retrieve a catalog node from an explicit Url. No searches will be preformed.
sPathUri	Since the node was not loaded by following the federated catalog system to an end point, you will have to tell the node it's name. Any name will worked and it's saved internally.
sAgent	The user agent string you wish to send to the server. If NULL then the string "libdas2/2.3" is sent.
pMgr	A credentials manager object to consult if a password is requested. May be set to NULL to indicate that only public items may be requested. Usually this is not needed as most catalog entries are public though the data sources they describe may not be.

Returns: A new DasNode object allocated on the heap, or NULL if object resolution failed. Use DasNode_type() to determine the which type of Catalog item was acquired.

DasNode * DasNode_subNode	(	DasNode *	pThis,
		const char *	sRelPath,
		DasCredMngr *	pMgr,
		const char *	sAgent
	)

Get a das2 catalog node contained item.

This function will search down the catalog hierarchy and find the requested node, downloading any intermediate nodes as needed. If the descendant node has already been downloaded no new network activity is generated.

Parameters

pThis	A pointer to a node of type D2C_CATALOG
sRelPath	the ID of the descendant node. This id is the portion that would be appended to this node's PathUri to make the complete URI of the final node. sRelPath does not need to start with the sub-item separator (if one is defined for this catalog) but may at the callers option. For example, both: ":/uiowa" and "uiowa" work for getting the uiowa subnode from the site catalog, but "/uiowa" would not since the separator defined for site is ":/".
sAgent	The user agent string you wish to send to the server. If NULL then the string "libdas2/2.3" is sent.
pMgr	A credentials manager object to consult if a password is requested. May be set to NULL to indicate that only public items may be requested.

Returns: A pointer to the child node, or NULL if no such child existed in the node cache nor could not be downloaded.

const char * DasNode_pathUri ( const DasNode * pThis )

Get the path URI for this catalog node.

Parameters

pThis the catalog node

Returns: A pointer to the path URI string. All catalog nodes have a path URI

const char * DasNode_srcUrl ( const DasNode * pThis )

Get the location from which this catalog node was read.

Parameters

pThis the catalog node

Returns: A pointer to the source URL string. All catalog nodes are loaded from somewhere, libdas2 does not provide functions to generate node objects programmatically.

das_node_type_e DasNode_type ( const DasNode * pThis )

Get the type of node This is a more specific question than the 'is' functions below, which should probably be used instead so that application code can work in a "duck-typing" manner.

Parameters

pThis the catalog node

Returns: The node type from the

const char * DasNode_name ( const DasNode * pThis )

Get the node title.

Parameters

pThis the catalog node

Returns: A string suitable for labeling this node in a GUI.

const DasJdo * DasNode_getJdo	(	const DasNode *	pThis,
		const char *	sFragment
	)

Get a JSON document object at a fragment location in a node.

Parameters

pThis	The catalog node
sFragment	The fragment path, for example "CONTACTS/TECH/0/EMAIL"

Returns: The json object at that location, or NULL if the node does not contain the given element.

const DasJdo * DasNode_getJdoType	(	const DasNode *	pThis,
		enum	das_json_type_e,
		const char *	sFragment
	)

Get a JSON document object of a particular type at a fragment location.

Parameters

pThis	The catalog node
type	The type of object expected
sFragment	The fragment path, for example "CONTACTS/TECH/0/EMAIL"

Returns: The json object at that location, or NULL if the node does not contain the given element, or if the given element is of the wrong type

void del_RootNode ( DasNode * pNode )

Delete a root node freeing it's memory.

All sub-nodes will be deleted as well.

The documentation for this struct was generated from the following file:

das2/node.h

Detailed Description

Public Member Functions

Member Function Documentation