Atom C Library Reference

Atom

Represents an Atom document. The Atom API allows one to download, create and modify Atom documents.

Create/Dispose

HCkAtom CkAtom_Create(void);

Creates an instance of the CkAtom object and returns a handle (i.e. a "void *" pointer). The handle is passed in the 1st argument for the functions listed on this page.

void CkAtom_Dispose(HCkAtom handle);

Objects created by calling CkAtom_Create must be freed by calling this method. A memory leak occurs if a handle is not disposed by calling this function.

C "Properties"

void CkAtom_getLastErrorHtml(HCkAtom handle, HCkString retval);

Error information in HTML format for the last method called.

void CkAtom_getLastErrorText(HCkAtom handle, HCkString retval);

Error information in plain-text format for the last method called.

void CkAtom_getLastErrorXml(HCkAtom handle, HCkString retval);

Error information in XML format for the last method called.

int CkAtom_getNumEntries(HCkAtom handle);

Number of entries in the Atom document.

BOOL CkAtom_getUtf8(HCkAtom handle);
void CkAtom_putUtf8(HCkAtom handle, BOOL newVal);

To be documented soon...

C "Methods"

int CkAtom_AddElement(HCkAtom handle, const char *tag, const char *value);

Adds a new element to the Atom document. The tag is a string such as "title", "subtitle", "summary", etc.

int CkAtom_AddElementDate(HCkAtom handle, const char *tag, SYSTEMTIME *dateTime);

Adds a new date-formatted element to the Atom document. The tag is a string such as "created", "modified", "issued", etc.

int CkAtom_AddElementHtml(HCkAtom handle, const char *tag, const char *htmlStr);

Adds a new HTML formatted element to the Atom document.

int CkAtom_AddElementXHtml(HCkAtom handle, const char *tag, const char *xmlStr);

Adds a new XHTML formatted element to the Atom document.

int CkAtom_AddElementXml(HCkAtom handle, const char *tag, const char *xmlStr);

Adds a new XML formatted element to the Atom document.

void CkAtom_AddEntry(HCkAtom handle, const char *xmlStr);

Adds an "entry" Atom XML document to the caller's Atom document.

void CkAtom_AddLink(HCkAtom handle, const char *rel, const char *href, const char *title, const char *typ);

Adds a link to the Atom document.

void CkAtom_AddPerson(HCkAtom handle, const char *tag, const char *name, const char *uri, const char *email);

Adds a person to the Atom document. The tag should be a string such as "author", "contributor", etc. If a piece of information is not known, an empty string or NULL value may be passed.

void CkAtom_DeleteElement(HCkAtom handle, const char *tag, int index);

Removes the Nth occurance of a given element from the Atom document. Indexing begins at 0. For example, to remove the 2nd category, set tag = "category" and index = 1.

void CkAtom_DeleteElementAttr(HCkAtom handle, const char *tag, int index, const char *attrName);

Remove an attribute from an element.The index should be 0 unless there are multiple elements having the same tag, in which case it selects the Nth occurrence based on the index ( 0 = first occurrence ).

void CkAtom_DeletePerson(HCkAtom handle, const char *tag, int index);

Deletes a person from the Atom document. The tag is a string such as "author". The index should be 0 unless there are multiple elements having the same tag, in which case it selects the Nth occurrence based on the index. For example, DeletePerson("author",2) deletes the 3rd author.

BOOL CkAtom_DownloadAtom(HCkAtom handle, const char *url);

Download an Atom feed from the Internet and load it into the Atom object.

Returns TRUE for success, FALSE for failure.

BOOL CkAtom_GetElement(HCkAtom handle, const char *tag, int index, HCkString outStr);

Returns the content of the Nth element having a specified tag.

BOOL CkAtom_GetElementAttr(HCkAtom handle, const char *tag, int index, const char *attrName, HCkString outStr);

Returns the value of an element's attribute. The element is selected by the tag name and the index (the Nth element having a specific tag) and the attribute is selected by name.

int CkAtom_GetElementCount(HCkAtom handle, const char *tag);

The number of elements having a specific tag.

BOOL CkAtom_GetElementDate(HCkAtom handle, const char *tag, int index, SYSTEMTIME *sysTime);

Returns an element's value as a Date.

HCkAtom CkAtom_GetEntry(HCkAtom handle, int index);

Returns the Nth entry as an Atom object. (Indexing begins at 0)

BOOL CkAtom_GetLinkHref(HCkAtom handle, const char *relName, HCkString outStr);

Returns the href attribute of the link having a specified "rel" attribute (such as "service.feed", "alternate", etc.).

BOOL CkAtom_GetPersonInfo(HCkAtom handle, const char *tag, int index, const char *tag2, HCkString outStr);

Returns a piece of information about a person. To get the 2nd author's name, call GetPersonInfo("author",1,"name").

BOOL CkAtom_GetTopAttr(HCkAtom handle, const char *attrName, HCkString outStr);

Returns the value of an attribute on the top-level XML node. The tag of a top-level Atom XML node is typically "feed" or "entry", and it might have attributes such as "xmlns" and "xml:lang".

BOOL CkAtom_HasElement(HCkAtom handle, const char *tag);

True (1) if the element exists in the Atom document. Otherwise 0.

BOOL CkAtom_LoadXml(HCkAtom handle, const char *xmlStr);

Loads the Atom document from an XML string.

void CkAtom_NewEntry(HCkAtom handle);

Initializes the Atom document to be a new "entry".

void CkAtom_NewFeed(HCkAtom handle);

Initializes the Atom document to be a new "feed".

BOOL CkAtom_SaveLastError(HCkAtom handle, const char *filename);

Saves the last error information to an XML formatted file.

void CkAtom_SetElementAttr(HCkAtom handle, const char *tag, int index, const char *attrName, const char *attrValue);

Adds or replaces an attribute on an element.

void CkAtom_SetTopAttr(HCkAtom handle, const char *attrName, const char *value);

Adds or replaces an attribute on the top-level XML node of the Atom document.

BOOL CkAtom_ToXmlString(HCkAtom handle, HCkString outStr);

Serializes the Atom document to an XML string.

void CkAtom_UpdateElement(HCkAtom handle, const char *tag, int index, const char *value);

Replaces the content of an element.

void CkAtom_UpdateElementDate(HCkAtom handle, const char *tag, int index, SYSTEMTIME *dateTime);

Replaces the content of a date-formatted element.

void CkAtom_UpdateElementHtml(HCkAtom handle, const char *tag, int index, const char *htmlStr);

Replaces the content of an HTML element.

void CkAtom_UpdateElementXHtml(HCkAtom handle, const char *tag, int index, const char *xmlStr);

Replaces the content of an XHTML element.

void CkAtom_UpdateElementXml(HCkAtom handle, const char *tag, int index, const char *xmlStr);

Replaces the content of an XML element.

void CkAtom_UpdatePerson(HCkAtom handle, const char *tag, int index, const char *name, const char *uri, const char *email);

Replaces the content of a person. To update the 3rd author, call UpdatePerson("author",2,"new name","new URL","new email"). If a piece of information is not known, pass an empty string or a NULL.

const char *CkAtom_getElement(HCkAtom handle, const char *tag, int index);

Returns the content of the Nth element having a specified tag.

const char *CkAtom_getElementAttr(HCkAtom handle, const char *tag, int index, const char *attrName);

Returns the value of an element's attribute. The element is selected by the tag name and the index (the Nth element having a specific tag) and the attribute is selected by name.

const char *CkAtom_getLinkHref(HCkAtom handle, const char *relName);

Returns the href attribute of the link having a specified "rel" attribute (such as "service.feed", "alternate", etc.).

const char *CkAtom_getPersonInfo(HCkAtom handle, const char *tag, int index, const char *tag2);

Returns a piece of information about a person. To get the 2nd author's name, call GetPersonInfo("author",1,"name").

const char *CkAtom_getTopAttr(HCkAtom handle, const char *attrName);

Returns the value of an attribute on the top-level XML node. The tag of a top-level Atom XML node is typically "feed" or "entry", and it might have attributes such as "xmlns" and "xml:lang".

const char *CkAtom_lastErrorHtml(HCkAtom handle);

Error information in HTML format for the last method called.

const char *CkAtom_lastErrorText(HCkAtom handle);

Error information in plain-text format for the last method called.

const char *CkAtom_lastErrorXml(HCkAtom handle);

Error information in XML format for the last method called.

const char *CkAtom_toXmlString(HCkAtom handle);

Serializes the Atom document to an XML string.