摘要 Libxml是一個有免費許可的用於處理XML、可以輕鬆跨越多個平臺的C語言庫。這個指南提供它的基本函數的例子。
緒論
Libxml 是一個實現讀、創建及操縱XML數據功能的C語言庫。這個指南提供例子代碼並給出它基本功能的解釋。在這個項目的主頁上有Libxml及更多關於它可用的資料。包含有完整的API文檔。這個指南並不能替代這些完整的文檔，但是闡明功能需要使用庫來完成基本操作。
這個指南基於一個簡單的XML應用，它使用我寫的一篇文章生成，它包含有元數據和文章的主體。
本指南中的例子代碼示範如何做到：
• 解析文檔
• 取得指定元素的文本
• 添加一個元素及它的內容
• 添加一個屬性
• 取得一個屬性的值
例子的完整代碼包含在附錄中
數據類型
Libxml 定義了許多數據類型，我們將反覆碰到它們，它隱藏了雜亂的來源以致你不必處理它除非你有特定的需要。xmlChar 替代char,使用UTF-8編碼的一字節字符串。如果你的數據使用其它編碼，它必須被轉換到UTF-8才能使用libxml的函數。在libxml編碼支持WEB頁面有更多關於編碼的有用信息。
XmlDoc 包含由解析文檔建立的樹結構，xmlDocPtr是指向這個結構的指針。
xmlNodePtr and xmlNode 包含單一結點的結構xmlNodePtr是指向這個結構的指針，它被用於遍歷文檔樹。
解析文檔
解析文檔時僅僅需要文件名並只調用一個函數，並有錯誤檢查。完整代碼：附錄C, Keyword例程代碼
①xmlDocPtr doc;
②xmlNodePtr cur;
③doc = xmlParseFile(docname);
④if (doc == NULL ) {
fprintf(stderr,"Document not parsed successfully. /n");
return;
}
⑤cur = xmlDocGetRootElement(doc);
⑥if (cur == NULL) {
fprintf(stderr,"empty document/n");
xmlFreeDoc(doc);
return;
}
⑦if (xmlStrcmp(cur->name, (const xmlChar *) "story")) {
fprintf(stderr,"document of the wrong type, root node != story");
xmlFreeDoc(doc);
return;
}
①定義解析文檔指針。
②定義結點指針(你需要它爲了在各個結點間移動)。
④檢查解析文檔是否成功，如果不成功，libxml將指一個註冊的錯誤並停止。
註釋
一個常見錯誤是不適當的編碼。XML標準文檔除了用UTF-8或UTF-16外還可用其它編碼保存。如果文檔是這樣，libxml將自動地爲你轉換到UTF-8。更多關於XML編碼信息包含在XML標準中。
⑤取得文檔根元素
⑥檢查確認當前文檔中包含內容。
⑦在這個例子中，我們需要確認文檔是正確的類型。“Story”是在這個指南中使用文檔的根類型。
取得元素內容
你找到在文檔樹中你要查找的元素後可以取得它的內容。在這個例子中我們查找“story”元素。進程將在冗長的樹中查找我們感興趣的元素。我們假定期你已經有了一個名爲doc的xmlDocPtr和一個名爲cur的xmlNodPtr。
①cur = cur->xmlChildrenNode;
②while (cur != NULL) {
if ((!xmlStrcmp(cur->name, (const xmlChar *)"storyinfo"))){
parseStory (doc, cur);
}
cur = cur->next;
}
①取得cur的第一個子結點，cur指向文檔的根，即“story”元素。
②這個循環迭代通過“story”的子元素查找“storyinfo”。這是一個包含有我們將查找的“keywords”的元素。它使用了libxml字符串比較函數xmlStrcmp。如果相符，它調用函數parseStory。
void
parseStory (xmlDocPtr doc, xmlNodePtr cur) {
xmlChar *key;
① cur = cur->xmlChildrenNode;
②while (cur != NULL) {
if ((!xmlStrcmp(cur->name, (const xmlChar *)"keyword"))) {
③ key = xmlNodeListGetString(doc, cur->xmlChildrenNode, 1);
printf("keyword: %s/n", key);
xmlFree(key);
}
cur = cur->next;
}
return;
}
① 再次取得第一個子結點。
② 像上面那個循環一樣，我們能過迭代，查找我們感興趣的叫做“keyword”的元素。
③ 當我們找到元素“keyword”時，我們需要打印它包含在XML中的記錄的內容，文本被包含於元素的子結點中，因此我們藉助了cur-> xmlChildrenNode，爲了取得文本，我們使用函數xmlNodeListGetString，它有一個文檔指針參數，在這個例子中，我們僅僅打印它。
註釋
因爲xmlNodeListGetString爲它返回的字符串分配內存，你必須使用xmlFree釋放它。
使用XPath取得元素內容
除了一步步遍歷文檔樹查找元素外，Libxml2包含支持使用Xpath表達式取得指定結點集。完整的Xpath API文檔在這裏。Xpath允許通過路徑文檔搜索匹配指定條件的結點。在下面的例子中，我們搜索文檔中所有的“keyword”元素。
註釋
下面是Xpath完整的討論。它詳細的使用資料，請查閱Xpath規範。
這個例子完整的代碼參見附錄D，XPath例程代碼。
Using XPath requires setting up an xmlXPathContext and then supplying the XPath expression and the context to the xmlXPathEvalExpression
function.
The function returns an xmlXPathObjectPtr, which includes the set of nodes satisfying the XPath expression.
使用XPath需要安裝xmlXPathContext才支持XPath表達式及xmlXPathEvalExpression函數，這個函數返回一個xmlXPathObjectPtr，它包含有
XPath表達式的結點集。
xmlXPathObjectPtr
getnodeset (xmlDocPtr doc, xmlChar *xpath){
①xmlXPathContextPtr context;
xmlXPathObjectPtr result;
②context = xmlXPathNewContext(doc);
③result = xmlXPathEvalExpression(xpath, context);
④if(xmlXPathNodeSetIsEmpty(result->nodesetval)){
printf("No result/n");
return NULL;
}
xmlXPathFreeContext(context);
return result;
}
①首先定義變量
②初始化變量context
③應用XPath表達式
④檢查結果
由函數返回的xmlPathObjectPtr包含一個結點集和其它需要被迭代及操作的信息。在這個例子中我們的函數返回 xmlXPathObjectPtr，我們使用它打印我們文檔中keyword結點的內容。這個結點集對象包含在集合(nodeNr)中的元素數目及一個結點(nodeTab)數組。
①for (i=0; i < nodeset->nodeNr; i++) {
②keyword = xmlNodeListGetString(doc,
nodeset->nodeTab[i]->xmlChildrenNode, printf("keyword: %s/n", keyword);
xmlFree(keyword);
}
①變量nodeset->Nr持有結點集中元素的數量。我們使用它遍歷數組。
②打印每個結點包含的內容。
註釋
Note that we are printing the child node of the node that is returned, because the contents of the keyword element are a child text node.注意我們打印的是結點的子結點的返回值，因爲keyword元素的內容是一個子文本結點。
寫元素
寫元素內容使用上面許多一樣的步驟—解析文檔並遍歷樹。我們先解析文檔然後遍歷樹查找我們想插入元素的位置。在這個例子中，我們再一次查找“storyinfo
”元素並插入一個keyword。然後我們裝文件寫入磁盤。完整代碼：附錄E，添加keyword例程
本例中主要的不同在於parseStory
void
parseStory (xmlDocPtr doc, xmlNodePtr cur, char *keyword) {
①xmlNewTextChild (cur, NULL, "keyword", keyword);
return;
}
①XmlNewTextChild函數添加一個當前結點的新的子元素到樹中
一旦結點被添加，我們應當寫文檔到文件中。你是否想給元素指定一個命名空間？你能添加它，在我們的例子中，命名空間是NULL。
xmlSaveFormatFile (docname, doc, 1);
第一個參數是寫入文件的名，你注意到和我們剛剛讀入的文件名是一樣的。在這個例子中，我們僅僅覆蓋原來的文件。第二個參數是一個xmlDoc結構指針，第三個參數設定爲1，保證在輸出上寫入。
libxml（二）
寫屬性
寫屬性類似於給一個新元素寫文本。在這個例子中，我們將添加一個reference結點URI屬性到我們的文檔中。完整代碼：附錄F，添加屬性例程代碼。 reference是story元素的一個子結點，所以找到並插入新元素及其屬性是簡單的。一旦我們在parseDoc進行了錯誤檢查，我們將在正確的位置加放我們的新元素。但進行之前我們需要定義一個此前我們不見過的數據類型。
xmlAttrPtr newattr;
我們也需要xmlNodePtr：
xmlNodePtr newnode;
剩下的parseDoc則和前面一樣，檢查根結點是否爲story。如果是的，那我們知道我們將在指定的位置添加我們的元素。
① newnode = xmlNewTextChild (cur, NULL, "reference", NULL);
②newattr = xmlNewProp (newnode, "uri", uri);
①使用xmlNewTextChild函數添國一個新結點到當前結點位置。
一旦結點被添加，文件應像前面的例子將我們添加的元素及文本內容寫入磁盤。
取得屬性
取得屬性值類似於前面我們取得一個結點的文本內容。在這個例子中，我們將取出我們在前一部分添加的URI的值。完整代碼：附錄G，取得屬性值例程代碼。
這個例子的初始步驟和前面是類似的：解析文檔，查找你感興趣的元素，然後進入一個函數完成指定的請求任務。在這個例子中，我們調用getReference。
void
getReference (xmlDocPtr doc, xmlNodePtr cur) {
xmlChar *uri;
cur = cur->xmlChildrenNode;
while (cur != NULL) {
if ((!xmlStrcmp(cur->name, (const xmlChar *)"reference"))) {
① uri = xmlGetProp(cur, "uri");
printf("uri: %s/n", uri);
xmlFree(uri);
}
cur = cur->next;
}
return;
}
① 關鍵函數是xmlGetProp,它返回一個包含屬性值的xmlChar。在本例中，我們僅僅打印它。
註釋
如果你使用DTD定義屬性的固定值或缺省值，這個函數也將取得它。
編碼轉換
數據編碼兼容問題是程序員新建普通的XML或特定XML時最常見的困難。按照這裏
稍後的討論來思考設計你的應用程序將幫助你避免這個困難。實際上，libxml能以UTF-8格式保存和操縱多種數據
你的程序使用其它的數據格式，比如常見的ISO-8859-1編碼，必須使用libxml函數轉換到UTF-8。如果你想你的程序以除UTF-8外的其它編碼方式輸出也必須做轉換。
如果能有效地轉換數據Libxml將使用轉換器。無轉換器時，僅僅UTF-8、UTF-16和ISO-8859-1能夠被作爲外部格式使用。有轉換器時，它能將從其它格式與UTF-8互換的任何格式均可使用。當前轉換器支持大約150種不同的編碼格式之間的相互轉換。實際支持的格式數量正在被實現。每一個實現在的轉換器儘可能的支持每一種格式。
警告
一個常見錯誤是在內部數據不同的部分使用不同的編碼格式。最常見的是情況是一個應用以ISO-8859-1作爲內部數據格式，結合libxml部分使用UTF-8格式。結果是一個應用程序要面對不同地內部數據格式。一部分代碼執行後，它或其它部分代碼將使用曲解的數據。
這個例子構造一個簡單的文檔，然後添加在命令行提供的內容到根元素並使用適當的編碼將結果輸出到標準輸出設備上。在這個例子中，我們使用ISO-8859 -1編碼。在命令輸入的內容將被從ISO-8859-1轉換到UTF-8。完整代碼：附件H，編碼轉換例程代碼。
包含在例子中的轉換函數使用libxml的xmlFindCharEncodingHandler函數。
①xmlCharEncodingHandlerPtr handler;
②size = (int)strlen(in)+1;
out_size = size*2-1;
out = malloc((size_t)out_size);
…
③handler = xmlFindCharEncodingHandler(encoding);
…
④handler->input(out, &out_size, in, &temp);
…
⑤xmlSaveFormatFileEnc("-", doc, encoding, 1);
①定義一個xmlCharEncodingHandler函數指針。
②XmlCharEncodingHandler函數需要給出輸入和輸出字符串的大小，這裏計算輸入輸出字符串。
③XmlFindCharEncodingHandler使用數據初始編碼作爲參數搜索libxml已經完成的轉換器句柄並將找到的函數指針返回，如果沒有找到則返回NULL。
④The conversion function identified by handler requires as its arguments pointers to the input and output strings, along with the length of each. The lengths must be determined separately by the application.
由句柄指定的轉換函數請求輸入、輸出字符中及它們的長度作爲參數。這個長度必須由應用程序分別指定。
⑤用指定編碼而不是UTF-8輸出，我們使用xmlSaveFormatFileEnc指不定期編碼方式。
A. 編譯
Libxml包含一個腳本xml2-config，它一般用於編譯和鏈接程序到庫時產生標誌。
爲了取得預處理和編譯標誌，使用xml2-config –cflags，爲了取得鏈接標誌，使用xml2-config –libs。其它有效的參數請使用xml2-config –help查閱。
B. 示例文檔
<?xml version="1.0"?>
<story>
<storyinfo>
<author>John Fleck</author>
<datewritten>June 2, 2002</datewritten>
<keyword>example keyword</keyword>
</storyinfo>
<body>
<headline>This is the headline</headline>
<para>This is the body text.</para>
</body>
</story>
C. Keyword例程代碼
#include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include <libxml/xmlmemory.h>
#include <libxml/parser.h>
void
parseStory (xmlDocPtr doc, xmlNodePtr cur) {
xmlChar *key;
cur = cur->xmlChildrenNode;
while (cur != NULL) {
if ((!xmlStrcmp(cur->name, (const xmlChar *)"keyword"))) {
key = xmlNodeListGetString(doc, cur->xmlChildrenNode, 1);
printf("keyword: %s/n", key);
xmlFree(key);
}
cur = cur->next;
}
return;
}
static void
parseDoc(char *docname) {
xmlDocPtr doc;
xmlNodePtr cur;
doc = xmlParseFile(docname);
if (doc == NULL ) {
fprintf(stderr,"Document not parsed successfully. /n");
return;
}
cur = xmlDocGetRootElement(doc);
if (cur == NULL) {
fprintf(stderr,"empty document/n");
xmlFreeDoc(doc);
return;
}
if (xmlStrcmp(cur->name, (const xmlChar *) "story")) {
fprintf(stderr,"document of the wrong type, root node != story");
xmlFreeDoc(doc);
return;
}
cur = cur->xmlChildrenNode;
while (cur != NULL) {
if ((!xmlStrcmp(cur->name, (const xmlChar *)"storyinfo"))){
parseStory (doc, cur);
}
cur = cur->next;
}
xmlFreeDoc(doc);
return;
}
int
main(int argc, char **argv) {
char *docname;
if (argc <= 1) {
printf("Usage: %s docname/n", argv[0]);
return(0);
}
docname = argv[1];
parseDoc (docname);
return (1);
}
libxml（三）
D. XPath例程代碼
#include <libxml/parser.h>
#include <libxml/xpath.h>
xmlDocPtr
getdoc (char *docname) {
xmlDocPtr doc;
doc = xmlParseFile(docname);
if (doc == NULL ) {
fprintf(stderr,"Document not parsed successfully. /n");
return NULL;
}
return doc;
}
xmlXPathObjectPtr
getnodeset (xmlDocPtr doc, xmlChar *xpath){
xmlXPathContextPtr context;
xmlXPathObjectPtr result;
context = xmlXPathNewContext(doc);
result = xmlXPathEvalExpression(xpath, context);
if(xmlXPathNodeSetIsEmpty(result->nodesetval)){
printf("No result/n");
return NULL;
}
xmlXPathFreeContext(context);
return result;
}
int
main(int argc, char **argv) {
char *docname;
xmlDocPtr doc;
xmlChar *xpath = ("//keyword");
xmlNodeSetPtr nodeset;
xmlXPathObjectPtr result;
int i;
xmlChar *keyword;
if (argc <= 1) {
printf("Usage: %s docname/n", argv[0]);
return(0);
}
docname = argv[1];
doc = getdoc(docname);
result = getnodeset (doc, xpath);
if (result) {
nodeset = result->nodesetval;
for (i=0; i < nodeset->nodeNr; i++) {
keyword = xmlNodeListGetString(doc, nodeset->nodeTab[i]->printf
("keyword: %s/n", keyword);
xmlFree(keyword);
}
xmlXPathFreeObject (result);
}
xmlFreeDoc(doc);
xmlCleanupParser();
return (1);
}
E. 添加keyword例程代碼
#include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include <libxml/xmlmemory.h>
#include <libxml/parser.h>
void
parseStory (xmlDocPtr doc, xmlNodePtr cur, char *keyword) {
xmlNewTextChild (cur, NULL, "keyword", keyword);
return;
}
xmlDocPtr
parseDoc(char *docname, char *keyword) {
xmlDocPtr doc;
xmlNodePtr cur;
doc = xmlParseFile(docname);
if (doc == NULL ) {
fprintf(stderr,"Document not parsed successfully. /n");
return (NULL);
}
cur = xmlDocGetRootElement(doc);
if (cur == NULL) {
fprintf(stderr,"empty document/n");
xmlFreeDoc(doc);
return (NULL);
}
if (xmlStrcmp(cur->name, (const xmlChar *) "story")) {
fprintf(stderr,"document of the wrong type, root node != story");
xmlFreeDoc(doc);
return (NULL);
}
cur = cur->xmlChildrenNode;
while (cur != NULL) {
if ((!xmlStrcmp(cur->name, (const xmlChar *)"storyinfo"))){
parseStory (doc, cur, keyword);
}
cur = cur->next;
}
return(doc);
}
int
main(int argc, char **argv) {
char *docname;
char *keyword;
xmlDocPtr doc;
if (argc <= 2) {
printf("Usage: %s docname, keyword/n", argv[0]);
return(0);
}
docname = argv[1];
keyword = argv[2];
doc = parseDoc (docname, keyword);
if (doc != NULL) {
xmlSaveFormatFile (docname, doc, 0);
xmlFreeDoc(doc);
}
return (1);
}
F. 添加屬性例程代碼
#include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include <libxml/xmlmemory.h>
#include <libxml/parser.h>
xmlDocPtr
parseDoc(char *docname, char *uri) {
xmlDocPtr doc;
xmlNodePtr cur;
xmlNodePtr newnode;
xmlAttrPtr newattr;
doc = xmlParseFile(docname);
if (doc == NULL ) {
fprintf(stderr,"Document not parsed successfully. /n");
return (NULL);
}
cur = xmlDocGetRootElement(doc);
if (cur == NULL) {
fprintf(stderr,"empty document/n");
xmlFreeDoc(doc);
return (NULL);
}
if (xmlStrcmp(cur->name, (const xmlChar *) "story")) {
fprintf(stderr,"document of the wrong type, root node != story");
xmlFreeDoc(doc);
return (NULL);
}
newnode = xmlNewTextChild (cur, NULL, "reference", NULL);
newattr = xmlNewProp (newnode, "uri", uri);
return(doc);
}
int
main(int argc, char **argv) {
char *docname;
char *uri;
xmlDocPtr doc;
if (argc <= 2) {
printf("Usage: %s docname, uri/n", argv[0]);
return(0);
}
docname = argv[1];
uri = argv[2];
doc = parseDoc (docname, uri);
if (doc != NULL) {
xmlSaveFormatFile (docname, doc, 1);
xmlFreeDoc(doc);
}
return (1);
}
G. 取得屬性值例程代碼
#include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include <libxml/xmlmemory.h>
#include <libxml/parser.h>
void
getReference (xmlDocPtr doc, xmlNodePtr cur) {
xmlChar *uri;
cur = cur->xmlChildrenNode;
while (cur != NULL) {
if ((!xmlStrcmp(cur->name, (const xmlChar *)"reference"))) {
uri = xmlGetProp(cur, "uri");
printf("uri: %s/n", uri);
xmlFree(uri);
}
cur = cur->next;
}
return;
}
void
parseDoc(char *docname) {
xmlDocPtr doc;
xmlNodePtr cur;
doc = xmlParseFile(docname);
if (doc == NULL ) {
fprintf(stderr,"Document not parsed successfully. /n");
return;
}
cur = xmlDocGetRootElement(doc);
if (cur == NULL) {
fprintf(stderr,"empty document/n");
xmlFreeDoc(doc);
return;
}
if (xmlStrcmp(cur->name, (const xmlChar *) "story")) {
fprintf(stderr,"document of the wrong type, root node != story");
xmlFreeDoc(doc);
return;
}
getReference (doc, cur);
xmlFreeDoc(doc);
return;
}
int
main(int argc, char **argv) {
char *docname;
if (argc <= 1) {
printf("Usage: %s docname/n", argv[0]);
return(0);
}
docname = argv[1];
parseDoc (docname);
return (1);
}
H. 編碼轉換例程代碼
#include <string.h>
#include <libxml/parser.h>
unsigned char*
convert (unsigned char *in, char *encoding)
{
unsigned char *out;
int ret,size,out_size,temp;
xmlCharEncodingHandlerPtr handler;
size = (int)strlen(in)+1;
out_size = size*2-1;
out = malloc((size_t)out_size);
if (out) {
handler = xmlFindCharEncodingHandler(encoding);
if (!handler) {
free(out);
out = NULL;
}
}
if (out) {
temp=size-1;
ret = handler->input(out, &out_size, in, &temp);
if (ret || temp-size+1) {
if (ret) {
printf("conversion wasn't successful./n");
} else {
printf("conversion wasn't successful. converted: }
free(out);
out = NULL;
} else {
out = realloc(out,out_size+1);
out[out_size]=0; /*null terminating out*/
}
} else {
printf("no mem/n");
}
return (out);
}
int
main(int argc, char **argv) {
unsigned char *content, *out;
xmlDocPtr doc;
xmlNodePtr rootnode;
char *encoding = "ISO-8859-1";
if (argc <= 1) {
printf("Usage: %s content/n", argv[0]);
return(0);
}
content = argv[1];
out = convert(content, encoding);
doc = xmlNewDoc ("1.0");
rootnode = xmlNewDocNode(doc, NULL, (const xmlChar*)"root", out);
xmlDocSetRootElement(doc, rootnode);
xmlSaveFormatFileEnc("-", doc, encoding, 1);
return (1);
}
…………………………………………………………………………………………
char *convert(char *instr,char *encoding)
{
xmlCharEncodingHandlerPtr handler;
xmlBufferPtr in,out;
handler = xmlFindCharEncodingHandler(encoding);
if(NULL != handler)
{
in = xmlBufferCreate();
xmlBufferWriteChar(in,instr);
out = xmlBufferCreate();
if(xmlCharEncInFunc(handler, out, in) 〈 0)
{
xmlBufferFree(in);
xmlBufferFree(out);
return NULL;
}
else
{
xmlBufferFree(in);
return (char *)out-〉content;
}
}
}
