| /******************************************************************************* |
| * Copyright (c) 2012 Wind River Systems, Inc. and others. |
| * All rights reserved. This program and the accompanying materials |
| * are made available under the terms of the Eclipse Public License v1.0 |
| * and Eclipse Distribution License v1.0 which accompany this distribution. |
| * The Eclipse Public License is available at |
| * http://www.eclipse.org/legal/epl-v10.html |
| * and the Eclipse Distribution License is available at |
| * http://www.eclipse.org/org/documents/edl-v10.php. |
| * You may elect to redistribute this code under either of these licenses. |
| * |
| * Contributors: |
| * Wind River Systems - initial API and implementation |
| *******************************************************************************/ |
| |
| /* |
| |
| This module implements a query based system to specify subsets of contexts. |
| The queries specifies context properties and what values they need to have to match. |
| In addition a query can filter based on a contexts ancestors in the context hierarchy. |
| |
| Syntax and Semantics |
| |
| query = [ "/" ], { part, "/" }, part ; |
| part = string | "*" | "**" | properties ; |
| properties = property, { ",", property } ; |
| property = string, "=", value ; |
| value = string | number | boolean ; |
| string = quoted string | symbol ; |
| quoted string = '"', {any-character - ('"' | '\') | ('\', ('"' | '\'))}, '"' ; |
| symbol = letter, { letter | digit } ; |
| number = digit, { digit } ; |
| boolean = "true" | "false" ; |
| letter = ? A-Z, a-z or _ ? ; |
| digit = ? 0-9 ? ; |
| any-character = ? any character ? ; |
| |
| To give a feel for the syntax, here are some examples, and what a user |
| might mean when providing such a query: |
| |
| httpd |
| Matches all contexts named "httpd". |
| |
| pid=4711 |
| Matches any context with a property pid, which has the value 4711. |
| |
| /server/ ** |
| Matches all contexts which are descendants of the top level context |
| named "server". |
| |
| "Linux 2.6.14"/Kernel/ * |
| Matches all kernel processes in operating systems named "Linux 2.6.14". |
| |
| pid=4711/ * |
| All threads in processes with the pid 4711. |
| |
| /server/ ** /HasState=true |
| All threads which are descendants of the context "server". |
| |
| The contexts are assumed to be placed in a tree. Each context has zero |
| or one parent. If it has zero parents it is a child of the root of the |
| tree. |
| |
| A query consists of a sequence of parts separated by "/". This |
| sequence specifies a path through the context tree. A context matches |
| the query if the last part of the query matches the properties of the |
| context and the parent of the context matches the query excluding the |
| last part. The properties of a context matches a part if each property |
| specified in the part matches the property of the same name in the |
| context or if the name of the context matches the string specified in |
| the part. There are also two wild cards. The part "*" matches any |
| context. The part "**" matches any sequence of contexts. If the query |
| starts with a "/" the first part of the query must match a child of |
| the root of the context tree. |
| |
| */ |
| |
| #ifndef D_contextquery |
| #define D_contextquery |
| |
| #include <tcf/framework/protocol.h> |
| #include <tcf/framework/context.h> |
| |
| /* An debug context back-end can register default comparator using this as the comparator name. |
| * Default comparator is used when a regular comparator not found for an attribute. |
| * As a cortesy to clients, back-end should register regular comparators when possible, |
| * because default comparator prevents clients from getting a list of supported attribute names. */ |
| #define DEFAULT_CONTEXT_QUERY_COMPARATOR "*" |
| |
| typedef int ContextQueryComparator(Context *, const char *); |
| typedef Context * GetContextParent(Context *); |
| |
| /* Register a function that compare a context attribute with a given pattern (value) */ |
| extern void add_context_query_comparator(const char * attr_name, ContextQueryComparator * callback); |
| |
| /* Parse context query string. Parsing results are stored in an internal buffer and |
| * and used by run_context_query() and run_context_query_ext() */ |
| extern int parse_context_query(const char * query); |
| |
| /* Compare context 'ctx' with parsed context query, return 1 if they match, return 0 othewise. */ |
| extern int run_context_query(Context * ctx); |
| extern int run_context_query_ext(Context * ctx, GetContextParent * get_parent); |
| |
| /* If called from ContextQueryComparator, return current attribute name. */ |
| extern const char * get_context_query_attr_name(void); |
| |
| /* Parse and run context query. |
| * Return 1 if the context and the query match, return 0 othewise. |
| * If a client needs to match multiple contexts, it is more efficient to call |
| * parse_context_query(), and then call run_context_query() for each context. |
| */ |
| extern int context_query(Context * ctx, const char * query); |
| |
| extern void ini_context_query_service(Protocol * proto); |
| |
| #endif /* D_contextquery */ |