1: /*
2: * LibAxl: Another XML library
3: * Copyright (C) 2006 Advanced Software Production Line, S.L.
4: *
5: * This program is free software; you can redistribute it and/or
6: * modify it under the terms of the GNU Lesser General Public License
7: * as published by the Free Software Foundation; either version 2.1 of
8: * the License, or (at your option) any later version.
9: *
10: * This program is distributed in the hope that it will be useful,
11: * but WITHOUT ANY WARRANTY; without even the implied warranty of
12: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13: * GNU Lesser General Public License for more details.
14: *
15: * You should have received a copy of the GNU Lesser General Public
16: * License along with this program; if not, write to the Free
17: * Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
18: * 02111-1307 USA
19: *
20: * You may find a copy of the license under this software is released
21: * at COPYING file. This is LGPL software: you are welcome to
22: * develop proprietary applications using this library without any
23: * royalty or fee but returning back any change, improvement or
24: * addition in the form of source code, project image, documentation
25: * patches, etc.
26: *
27: * For commercial support on build XML enabled solutions contact us:
28: *
29: * Postal address:
30: * Advanced Software Production Line, S.L.
31: * Edificio Alius A, Oficina 102,
32: * C/ Antonio Suarez Nº 10,
33: * Alcalá de Henares 28802 Madrid
34: * Spain
35: *
36: * Email address:
37: * info@aspl.es - http://www.aspl.es/xml
38: */
39: #include <axl_ns.h>
40:
41: #define LOG_DOMAIN "axl-ns-doc"
42:
43: /**
44: * \defgroup axl_ns_doc_module Axl Doc Namespace: Xml 1.0 namespace support for XML documents
45: */
46:
47: /**
48: * \addtogroup axl_ns_doc_module
49: * @{
50: */
51:
52: /**
53: * @internal Name of the key used to access and store the ns table for
54: * each node.
55: */
56: #define NS_TABLE "__axl:ns-table"
57:
58:
59: /**
60: * @internal Table used to hold bindings from prefix declared and
61: * namespaces used. It also holds the default namespace declared for a
62: * particular node, refering to it and all its content until found
63: * another declaration.
64: */
65: typedef struct _axlNsTable {
66: /* bindings between prefixes and namespaces */
67: axlHash * table;
68:
69: /* default namespace to be used */
70: const char * defaultNs;
71: } axlNsTable;
72:
73: void __axl_ns_free_table (axlNsTable * table)
74: {
75: if (table == NULL)
76: return;
77:
78: /* free table */
79: axl_hash_free (table->table);
80:
81: /* free node */
82: axl_free (table);
83:
84: return;
85: } /* end __axl_ns_free_table */
86:
87: /* check and install all ns declerations found on this node */
88: axl_bool __axl_ns_node_check_and_install_ns_decls (axlNode * node, axlAttrCursor * cursor, axlError ** error)
89: {
90: const char * attr;
91: axl_bool default_found = axl_false;
92: axlNsTable * ns_table = NULL;
93:
94: /* for each attribute installed on the node */
95: while (axl_node_attr_cursor_has_item (cursor)) {
96:
97: /* get the key */
98: attr = axl_node_attr_cursor_get_key (cursor);
99: if (! axl_memcmp (attr, "xmlns", 5)) {
100: /* no xml namespace declaration found, go next */
101: axl_node_attr_cursor_next (cursor);
102: continue;
103: } /* end if */
104:
105: /* create the table (without creating the hash for now) */
106: if (ns_table == NULL) {
107: ns_table = axl_new (axlNsTable, 1);
108:
109: /* install the table in the node */
110: axl_node_annotate_data_full (node,
111: /* key and its destroy function */
112: NS_TABLE, NULL,
113: /* value and its destroy function */
114: ns_table, (axlDestroyFunc)__axl_ns_free_table);
115: } /* end if */
116:
117: /* check if we have a default xmlns declaration */
118: if (strlen (attr) == 5) {
119: /* check if there were previous xmlns default declarations */
120: if (default_found) {
121: /* free cursor */
122: axl_node_attr_cursor_free (cursor);
123:
124: axl_error_new (-1, "Found that the document defines several default xmlns declarations at the same node", NULL, error);
125: return axl_false;
126: } /* end if */
127: default_found = axl_true;
128:
129: /* copy the default namespace */
130: ns_table->defaultNs = axl_node_attr_cursor_get_value (cursor);
131:
132: /* go next */
133: axl_node_attr_cursor_next (cursor);
134: continue;
135:
136: } /* end if */
137:
138: /* found preffixed namespace declaration */
139: if (ns_table->table == NULL) {
140: /* create the table with 1 step */
141: ns_table->table = axl_hash_new_full (axl_hash_string, axl_hash_equal_string, 1);
142: } /* end if */
143:
144: /* check that the prefix wasn't declared at the same node */
145: attr = attr + 6;
146: if (axl_hash_exists (ns_table->table, (axlPointer) attr)) {
147: /* free cursor */
148: axl_node_attr_cursor_free (cursor);
149:
150: axl_error_new (-1, "Found that the document already declares the same prefix for the same node several times",
151: NULL, error);
152: return axl_false;
153: } /* end if */
154:
155: /* install it in the current ns hash table */
156: axl_hash_insert (ns_table->table, (axlPointer) attr, (axlPointer) axl_node_attr_cursor_get_value (cursor));
157:
158: /* get next attribute */
159: axl_node_attr_cursor_next (cursor);
160:
161: } /* end while */
162:
163: /* all declarations done */
164: return axl_true;
165:
166: } /* end __axl_ns_node_check_and_install_ns_decls */
167:
168: /**
169: * @internal Function that validates the node against current status
170: * of the namespace support.
171: */
172: axl_bool __axl_ns_node_validate (axlNode * node, axlError ** error)
173: {
174: int iterator = 0;
175: char * name;
176: axl_bool found = axl_false;
177: axlNsTable * ns_table;
178: axlNode * parent;
179: axlNode * child;
180:
181: /* create the cursor */
182: axlAttrCursor * cursor = NULL;
183:
184: /* check if the node has a namespace declaration */
185: if (axl_node_has_attributes (node)) {
186:
187: /* the node has attributes, check if there are some
188: * namespace declaration */
189: cursor = axl_node_attr_cursor_new (node);
190:
191: /* check and install all ns declerations found on this
192: * node (cursor is dellocated by this function on
193: * error) */
194: if (! __axl_ns_node_check_and_install_ns_decls (node, cursor, error))
195: return axl_false;
196:
197: } /* end if */
198:
199: /* now we have all namespace declarations, check that the node
200: * name and its attributes are properly declared */
201: name = (char*) axl_node_get_name (node);
202:
203: /* check if the node name uses a namespace scope declaration
204: * (prefix:name) */
205: while (name[iterator] != 0) {
206: if (name[iterator] == ':') {
207: /* set the terminator */
208: name[iterator] = 0;
209:
210: /* namespace node found */
211: found = axl_true;
212: break;
213: }
214:
215: /* get next position */
216: iterator++;
217: } /* end if */
218:
219: if (found) {
220: /* namespace declaration found (this supposes that the
221: * default ns is not used) */
222: parent = node;
223: while (parent != NULL) {
224: /* try to get the ns table having the prefix declaration */
225: ns_table = axl_node_annotate_get (parent, NS_TABLE, axl_false);
226:
227: /* check the namespace */
228: if (ns_table != NULL && axl_hash_exists (ns_table->table, name)) {
229: /* prefix found, restore node name */
230: name[iterator] = ':';
231: break;
232: } /* end if */
233:
234: /* get the parent */
235: parent = axl_node_get_parent (parent);
236:
237: /* no more parents */
238: if (parent == NULL) {
239: /* prefix not found, restore node name */
240: name[iterator] = ':';
241:
242: /* free cursor */
243: axl_node_attr_cursor_free (cursor);
244:
245: axl_error_new (-1, "Found prefix declaration for which a namespace binding wasn't found in the node or any parent (xmlns:prefix='ns')",
246: NULL, error);
247: return axl_false;
248: } /* end if */
249: } /* end while */
250: } /* end if */
251:
252: /* check if the node has a namespace declaration */
253: if (axl_node_has_attributes (node)) {
254: /* now check attributes */
255: axl_node_attr_cursor_first (cursor);
256: while (axl_node_attr_cursor_has_item (cursor)) {
257:
258: /* get the key */
259: name = (char*) axl_node_attr_cursor_get_key (cursor);
260: if (axl_memcmp (name, "xmlns", 5)) {
261: /* skip namespace declarations */
262: axl_node_attr_cursor_next (cursor);
263: continue;
264: } /* end if */
265:
266: __axl_log (LOG_DOMAIN, AXL_LEVEL_DEBUG, "checking attribute name='%s'", name);
267:
268: /* check if the node name uses a namespace scope declaration
269: * (prefix:name) */
270: found = axl_false;
271: iterator = 0;
272: while (name[iterator] != 0) {
273: if (name[iterator] == ':') {
274: /* set the terminator */
275: name[iterator] = 0;
276:
277: /* namespace node found */
278: found = axl_true;
279: break;
280: }
281:
282: /* get next position */
283: iterator++;
284: } /* end while */
285:
286: if (found) {
287: parent = node;
288: while (parent != NULL) {
289: /* try to get the ns table having the prefix declaration */
290: ns_table = axl_node_annotate_get (parent, NS_TABLE, axl_false);
291:
292: /* check the namespace */
293: if (ns_table != NULL && axl_hash_exists (ns_table->table, name)) {
294: /* prefix found, restore attribute name */
295: name[iterator] = ':';
296: break;
297: } /* end if */
298:
299: /* get the parent */
300: parent = axl_node_get_parent (parent);
301:
302: /* no more parents */
303: if (parent == NULL) {
304: /* prefix not found, restore attribute name */
305: name[iterator] = ':';
306:
307: /* free cursor */
308: axl_node_attr_cursor_free (cursor);
309:
310: axl_error_new (-1, "Found prefix declaration, for an attribute, for which a namespace binding wasn't found in the node or any parent (xmlns:prefix='ns')",
311: NULL, error);
312: return axl_false;
313: } /* end if */
314: } /* end while */
315: } /* end if */
316:
317: /* next attribute */
318: axl_node_attr_cursor_next (cursor);
319:
320: } /* end while */
321:
322: /* free cursor */
323: axl_node_attr_cursor_free (cursor);
324:
325: } /* end if */
326:
327: /* do the same for the rest of the child nodes */
328: child = axl_node_get_first_child (node);
329: while (child != NULL) {
330: /* check childs */
331: if (! __axl_ns_node_validate (child, error))
332: return axl_false;
333:
334: /* go next child node */
335: child = axl_node_get_next (child);
336: } /* end while */
337:
338: /* return axl_true, if reached this place */
339: return axl_true;
340: }
341:
342: /**
343: * @brief Allows to check XML 1.0 namespace rules for the document
344: * loaded.
345: *
346: * XML 1.0 Namespaces definition allows you to define documents that
347: * are resistent to tag clashing, making your product to be more
348: * usable at any level, being mixed with other products.
349: *
350: * This function allows you to check a xml document, already loaded
351: * with the Axl Doc base API (\ref axl_doc_parse_from_file, \ref
352: * axl_doc_parse or \ref axl_doc_create), if it follows the namespaces
353: * contrains (XML 1.0 Namespaces http://www.w3.org/TR/REC-xml-names/).
354: *
355: * The idea behind this function is to ensure that the document has
356: * the proper XML 1.0 Namespace declarations, which will be used by
357: * the following function to help you detect those tags recognized by
358: * your XML software, ensuring this matching is done inside your
359: * namespace:
360: *
361: * - \ref axl_ns_node_cmp
362: * - \ref axl_ns_node_find_called
363: * - See \ref axl_ns_node_module "Axl namespace support for nodes" to get more information about function used to read your xml documents in a namespace aware manner.
364: *
365: * Here is a simple example on how to load a xml document, add
366: * namespace checking support, and read content inside without
367: * compromissing your code to node tag collitions:
368: *
369: * \include ns_example.c
370: *
371: * As a gold rule, your code must not use prefixed names (full
372: * qualified names) to check xml node names (tags), because they will
373: * make your code fragile to changes introduced in xml documents read
374: * by your application.
375: *
376: * Instead, you must provide your namespace where the validation will take
377: * place and the local name of the node being checked (knowing that
378: * the prefix and the local name for <b><shaper:xml-rpc-invoke></b> is
379: * <b>shaper</b> and <b>xml-rpc-invoke</b> respectively).
380: *
381: * Let's see an an example to clarify this. Assuming the following xml document:
382: *
383: * <div class="xml-doc">
384: * \include ns_shaper.xml
385: * </div>
386: *
387: * Previous examples shows a simple shaper description, which is using
388: * <b>shaper</b> as prefix for its nodes. Under this situation you
389: * must not use the following to check for an xml node name:
390: *
391: * \code
392: * if (NODE_CMP_NAME (node, "shaper:xml-rpc-invoke")) {
393: * // found shaper:xml-rpc-invoke tag
394: * }
395: * \endcode
396: *
397: * This is because, as we have said, you are placing direct references
398: * to the namespace prefix declared at the document, but this is
399: * wrong. You can't ensure the user won't change the namespace binding
400: * that links your namespace with the prefix <b>shaper</b>.
401: *
402: * The proper way to check xml node names (tags) in a namespace aware
403: * manner is:
404: *
405: * \code
406: * // supposing SHAPER_NS defines the namespace string
407: * if (axl_ns_node_cmp (node, SHAPER_NS, "xml-rpc-invoke")) {
408: * // found xml-rpc-invoke tag
409: * }
410: * \endcode
411: *
412: * Now, the user will be able to change the binding between your
413: * namespace and the prefix used. This will enable him to use the
414: * prefix <b>shaper</b> for its products, without breaking your
415: * software.
416: *
417: * <i><b>NOTE:</b> providing a document without content (at least one
418: * root node configured), will cause the function to return \ref
419: * axl_true.</i>
420: *
421: * @param doc The document that is being required to be checked
422: * against the XML Namespaces 1.0 rules.
423: *
424: * @param error An optional variable where errors will be reported. If
425: * the function returns \ref axl_false, you can call to \ref axl_error_get
426: * to get a textual diagnostic.
427: *
428: * @return \ref axl_true if the document is namespace-valid, otherwise,
429: * \ref axl_false is returned.
430: */
431: axl_bool axl_ns_doc_validate (axlDoc * doc, axlError ** error)
432: {
433: axlNode * node;
434:
435: /* check references */
436: if (doc == NULL) {
437: axl_error_new (-1, "Document provided is a null reference", NULL, error);
438: return axl_false;
439: } /* end if */
440:
441: /* get root document */
442: node = axl_doc_get_root (doc);
443: if (node == NULL) {
444: /* document has no nodes, return axl_true */
445: return axl_true;
446: } /* end if */
447:
448: /* call to produce and validate namespace content */
449: return __axl_ns_node_validate (node, error);
450: }
451:
452: /**
453: * @internal Internal API that allows to check if the provided prefix
454: * (ns_prefix) is bound to the provided namespace, using the node
455: * provided as a reference for the parent lookup.
456: *
457: * @param node The node that is used as reference for the
458: * lookup. Starting from this node the lookup will be performed,
459: * following with parents.
460: *
461: * @param ns_prefix The ns prefix to be checked.
462: *
463: * @param ns The namespace that must be bound the prefix.
464: *
465: * @return axl_true if the prefix is bound to the namespace provided,
466: * using the node as reference for all declarations found inside the
467: * particular node (or its parents).
468: */
469: axl_bool axl_ns_doc_node_check (axlNode * node,
470: const char * ns_prefix,
471: const char * ns)
472: {
473: axlNode * parent = node;
474: axlNsTable * ns_table = NULL;
475:
476: /* foreach node, up to the root parent, starting from the node
477: * provided, do: */
478: while (parent != NULL) {
479: /* try to get the ns table having the prefix declaration */
480: ns_table = axl_node_annotate_get (parent, NS_TABLE, axl_false);
481:
482: /* check the namespace */
483: if (ns_table != NULL && axl_hash_exists (ns_table->table, (axlPointer) ns_prefix)) {
484: /* prefix found, check its value */
485: return axl_cmp (axl_hash_get (ns_table->table, (axlPointer) ns_prefix), ns);
486: } /* end if */
487:
488: /* not found, get the parent */
489: parent = axl_node_get_parent (parent);
490:
491: } /* end while */
492:
493: /* reached this point, return axl_false */
494: return axl_false;
495: }
496:
497: /**
498: * @internal Function that allows to check if the default namespace is
499: * the value provided, using as reference, the node received.
500: *
501: * @param node The node to check for its default namespace to match
502: * the value provided.
503: *
504: * @param ns The namespace that is provided to match.
505: *
506: * @return \ref axl_true if the node has as default namespace the value
507: * received. Otherwise \ref axl_false is returned.
508: */
509: axl_bool axl_ns_doc_check_default (axlNode * node,
510: const char * ns)
511: {
512: axlNode * parent = node;
513: axlNsTable * ns_table = NULL;
514:
515: /* foreach node, up to the root parent, starting from the node
516: * provided, do: */
517: while (parent != NULL) {
518: /* try to get the ns table having the prefix declaration */
519: ns_table = axl_node_annotate_get (parent, NS_TABLE, axl_false);
520:
521: /* check the namespace */
522: if (ns_table != NULL && ns_table->defaultNs != NULL) {
523: /* prefix found, check its value */
524: return axl_cmp (ns_table->defaultNs, ns);
525: } /* end if */
526:
527: /* not found, get the parent */
528: parent = axl_node_get_parent (parent);
529:
530: } /* end while */
531:
532: /* reached this point, return axl_false */
533: return axl_false;
534: }
535:
536: /**
537: * @}
538: */
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to axl_ns_doc.c CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / gpl / axl / ns