Grid Application Toolkit A simple API for Grid Applications

Menu Home API-Specification API-Overview Status C Reference Manual Download Java Java-Reference General GridLab - WP-1 Links

GATLocation.h Go to the documentation of this file. /** @file GATLocation.h * Header file for the GATLocation class. * * An instance of this class represents the location of an abstract * or physical resource. The location of an abstract or physical * resource is represented by a URI as defined by the standards * <ul> * <li>RFC 2396: Uniform Resource Identifiers (URI): Generic Syntax</li> * <li> RFC 2732: Format for Literal IPv6 Addresses in URLs.</li> * </ul> * One should refer to these standards to determine the allowed forms * for URIs. This class provides a means to create a GATLocation * instance from a "URI in String form," operations for * accessing the various components of the contained URI, and various * other utility operations. * * @date $Date: 2004/03/24 19:30:58 $ * * @version $Header: /export/cvs-gridlab/wp-1/Codes/GATEngine/C-reference/src/GATLocation.h,v 1.19 2004/03/24 19:30:58 hartmutkaiser Exp $ * * Copyright (C) Kelly Davis * This file is part of the GAT Engine. * Contributed by Kelly Davis <kdavis@aei.mpg.de>. * * Copyright (C) Tom Goodale * This file is part of the GAT Engine. * Contributed by Tom Goodale <goodale@aei.mpg.de>. * * Use, modification and distribution is subject to the Gridlab Software * License. (See accompanying file GLlicense.txt or copy at * http://www.gridlab.org/GLlicense.txt) */ #ifndef _GATLOCATION_H_ #define _GATLOCATION_H_ 1 #include "GATType.h" #include "GATObject.h" #ifdef __cplusplus extern "C" { #endif /* Declare the converters to/from GATObject */ GATOBJECT_DECLARE_CONVERTERS(GATLocation); /** * Constructs a GATLocation instance by parsing the given String as a URI. * <p> * This constructor parses the given String exactly as specified by the * grammar in RFC 2396, Appendix A, except IPv6 addresses are permitted * for the host component. An IPv6 address must be enclosed in square * brackets (`[' and `]') as specified by RFC 2732. The IPv6 address * itself must parse according to RFC 2373. IPv6 addresses are further * constrained to describe no more than sixteen bytes of address * information, a constraint implicit in RFC 2373 but not expressible in * the grammar. * * @param url URI for the Location. * @return A new GATLocation */ GATLocation GATLocation_Create(const char *uri); /** * Destroys this GATLocation object * * @param this The GATLocation to destroy */ void GATLocation_Destroy(GATLocation *loc); /** * Tests this GATLocation for equality with the passed GATLocations. * <p> * For two GATLocations to be considered equal requires that either both * are opaque or both are hierarchical. Their schemes must either both * be undefined or else be equal without regard to case, and similarly * for their fragments. * <p> * For two opaque GATLocations to be considered equal, their * scheme-specific parts must be equal. * <p> * For two hierarchical GATLocations to be considered equal, their paths * must be equal and their queries must either both be undefined or else * be equal. Their authorities must either both be undefined, or both * be registry-based, or both be server-based. If their authorities are * defined and are registry-based, then they must be equal. If their * authorities are defined and are server-based, then their hosts must * be equal without regard to case, their port numbers must be equal, * and their user-information components must be equal. * <p> * When testing the user-information, path, query, fragment, authority, * or scheme-specific parts of two GATLocations for equality, the raw forms * rather than the encoded forms of these components are compared and * the hexadecimal digits of escaped octets are compared without regard * to case. * * @param this The first GATLocation * @param that The second GATLocation * @return 1 upon equality 0 otherwise */ int GATLocation_Equals(GATLocation_const lhs, GATLocation_const rhs, GATBool *isequal); /** GATResult GATLocation_GetInterface(GATLocation_const file, GATInterface iftype, void const **ifp) * @brief Get an interface supported by a GATObject * * The function GATLocation_GetInterface allows to get a pointer to an * additional interface supported by this GATLocation. * * @param object The object to be asked for the new interface. * @param iftype The interface the object is to be asked for. * @param ifp The pointer, through which the result is to be returned. * * @return An error type. */ GATResult GATLocation_GetInterface(GATLocation_const object, GATInterface iftype, void const **ifp); /** * Returns the decoded authority component of this GATLocation. * <p> * A sequence of escaped octets is decoded by replacing it with the * sequence of characters that it represents in the UTF-8 character set. * UTF-8 contains US-ASCII, hence decoding has the effect of de-quoting * any quoted US-ASCII characters as well as that of decoding any encoded * non-US-ASCII characters. If a decoding error occurs when decoding the * escaped octets then the erroneous octets are replaced by * `\uFFFD', the Unicode replacement character. * <p> * The String returned by this operation is equal to that returned by the * GetRawAuthority operation except that all sequences of escaped octets are * decoded. * * @param this The GATLocation to query * @retrun Decoded authority component of this GATLocation, or null if * authority is undefined */ char *GATLocation_GetAuthority(GATLocation_const loc); /** * Returns the raw authority component of this GATLocation. * <p> * The authority component of a GATLocation, if defined, only contains the * commercial-at character (`@') and characters in the unreserved, punct, * escaped, and other categories. If the authority is server-based then * it is further constrained to have valid user-information, host, and * port components. * * @param this The GATLocation to query * @return Raw authority component of this GATLocation, or null if authority * is undefined. */ char *GATLocation_GetRawAuthority(GATLocation_const loc); /** * Returns the decoded fragment component of this GATLocation. * <p> * A sequence of escaped octets is decoded by replacing it with the * sequence of characters that it represents in the UTF-8 character set. * UTF-8 contains US-ASCII, hence decoding has the effect of de-quoting * any quoted US-ASCII characters as well as that of decoding any encoded * non-US-ASCII characters. If a decoding error occurs when decoding the * escaped octets then the erroneous octets are replaced by * `\uFFFD', the Unicode replacement character. * <p> * The String returned by this operation is equal to that returned by the * GetRawFragment operation except that all sequences of escaped octets are * decoded. * * @param this The GATLocation to query * @return The decoded fragment component of this GATLocation, * or null if fragment is undefined. */ char *GATLocation_GetFragment(GATLocation_const loc); /** * Returns the raw fragment component of this GATLocation. * <p> * The fragment component of a GATLocation, if defined, only contains legal * URI characters. * * @param this The GATLocation to query * @return Raw fragment component of this GATLocation, or null if fragment is * undefined */ char *GATLocation_GetRawFragment(GATLocation_const loc); /** * Returns the host component of this GATLocation. * <p> * The host component of a GATLocation, if defined, will have one of the * following forms: * <ul> * <li>A domain name consisting of one or more labels separated by * period characters (`.'), optionally followed by a period character. * Each label consists of alphanum characters as well as hyphen characters * (`-'), though hyphens never occur as the first or last characters * in a label. The last, or only, label in a domain name begins with an * alpha character.</li> * <li>A dotted-quad IPv4 address of the form digit+.digit+.digit+.digit+, * where no digit sequence is longer than three characters and no sequence * has a value larger than 255.</li> * <li>An IPv6 address enclosed in square brackets (`[' and `]') and * consisting of hexadecimal digits, colon characters (`:'), and possibly * an embedded IPv4 address. The full syntax of IPv6 addresses is specified * in RFC 2373: IPv6 Addressing Architecture.</li> * </ul> * <p> * The host component of a GATLocation cannot contain escaped octets, * hence this operation does not perform any decoding. * * @param this The GATLocation to query * @retrun Host component of this GATLocation, or null if host is undefined. */ char *GATLocation_GetHost(GATLocation_const loc); /** * Returns the decoded path component of this GATLocation. * <p> * A sequence of escaped octets is decoded by replacing it with the * sequence of characters that it represents in the UTF-8 character set. * UTF-8 contains US-ASCII, hence decoding has the effect of de-quoting * any quoted US-ASCII characters as well as that of decoding any * encoded non-US-ASCII characters. If a decoding error occurs when * decoding the escaped octets then the erroneous octets are replaced by * `\uFFFD', the Unicode replacement character. * <p> * The String returned by this operation is equal to that returned by the * GetRawPath operation except that all sequences of escaped octets are * decoded. * * @param this The GATLocation to query * @return Decoded path component of this GATLocation, or null if path is * undefined. */ char *GATLocation_GetPath(GATLocation_const loc); /** * Returns the raw path component of this GATLocation. * <p> * The path component of a URI, if defined, only contains the slash * character (`/'), the commercial-at character (`@'), and characters in * the unreserved, punct, escaped, and other categories. * * @param this The GATLocation to query * @return Raw path component of this GATLocation, or null if path is * undefined. */ char *GATLocation_GetRawPath(GATLocation_const loc); /** * Returns the port number of this GATLocation. * <p> * The port component of a URI, if defined, is a non-negative integer. * * @param this The GATLocation to query * @return Port component of this URI, or -1 if the port is undefined. */ int GATLocation_GetPort(GATLocation_const loc); /** * Returns the decoded query component of this GATLocation. * <p> * A sequence of escaped octets is decoded by replacing it with the * sequence of characters that it represents in the UTF-8 character set. * UTF-8 contains US-ASCII, hence decoding has the effect of de-quoting * any quoted US-ASCII characters as well as that of decoding any * encoded non-US-ASCII characters. If a decoding error occurs when * decoding the escaped octets then the erroneous octets are replaced by * `\uFFFD', the Unicode replacement character. * <p> * The String returned by this operation is equal to that returned by the * GetRawQuery operation except that all sequences of escaped octets are * decoded. * * @param this The GATLocation to query * @return Decoded query component of this GATLocation, or null if query * is undefined. */ char *GATLocation_GetQuery(GATLocation_const loc); /** * Returns the raw query component of this GATLocation. * <p> * The query component of a URI, if defined, only contains legal URI * characters. * * @param this The GATLocation to query * @return Raw query component of this GATLocation, or null if query is * undefined. */ char *GATLocation_GetRawQuery(GATLocation_const loc); /** * Returns the scheme component of this GATLocation. * <p> * The scheme component of a URI, if defined, only contains characters * in the alphanum category and in the String "-.+". A scheme always * starts with an alpha character. * <p> * The scheme component of a URI cannot contain escaped octets, hence * this operation does not perform any decoding. * * @param this The GATLocation to query * @return Scheme component of this GATLocation, or null if scheme is * undefined. */ char *GATLocation_GetScheme(GATLocation_const loc); /** * Returns the decoded scheme-specific part of this GATLocation. * <p> * A sequence of escaped octets is decoded by replacing it with the * sequence of characters that it represents in the UTF-8 character set. * UTF-8 contains US-ASCII, hence decoding has the effect of de-quoting * any quoted US-ASCII characters as well as that of decoding any * encoded non-US-ASCII characters. If a decoding error occurs when * decoding the escaped octets then the erroneous octets are replaced by * `\uFFFD', the Unicode replacement character. * <p> * The String returned by this operation is equal to that returned by the * GetRawSchemeSpecificPart operation except that all sequences of escaped * octets are decoded * * @param this The GATLocation to query * @return Decoded scheme-specific component of this GATLocation (never null) */ char *GATLocation_GetSchemeSpecificPart(GATLocation_const loc); /** * Returns the raw scheme-specific part of this GATLocation. The * scheme-specific part is never undefined, though it may be empty. * <p> * The scheme-specific part of a URI only contains legal URI characters. * * @param this The GATLocation to query * @return Raw scheme-specific component of this GATLocation (never null). */ char *GATLocation_GetRawSchemeSpecificPart(GATLocation_const loc); /** * Returns the decoded user-information component of this GATLocation. * <p> * A sequence of escaped octets is decoded by replacing it with the * sequence of characters that it represents in the UTF-8 character set. * UTF-8 contains US-ASCII, hence decoding has the effect of de-quoting * any quoted US-ASCII characters as well as that of decoding any * encoded non-US-ASCII characters. If a decoding error occurs when * decoding the escaped octets then the erroneous octets are replaced by * `\uFFFD', the Unicode replacement character. * <p> * The String returned by this operation is equal to that returned by the * GetRawUserInfo operation except that all sequences of escaped octets are * decoded. * * @param this The GATLocation to query * @return Decoded user-information component of this GATLocation, or null * if it is undefined. */ char *GATLocation_GetUserInfo(GATLocation_const loc); /** * Returns the raw user-information component of this GATLocation. * <p> * The user-information component of a URI, if defined, only contains * characters in the unreserved, punct, escaped, and other categories. * * @param this The GATLocation to query * @return Raw user-information component of this GATLocation, or null * if it is undefined. */ char *GATLocation_GetRawUserInfo(GATLocation_const loc); /** * Returns the content of this GATLocation as a String. * <p> * A String equivalent to the input string given to the GATLocation * constructor, or to the String computed from the originally-given * components, as appropriate, is returned. * * @param this The GATLocation to query * @return The string form of this GATLocation */ char *GATLocation_ToString(GATLocation_const loc); /** * Returns a deep clone of this GATLocation. * * @param this The GATLocation to query * @return A clone of this GATLocation. */ int GATLocation_Clone(GATLocation_const loc, GATLocation *new_location); /** * Returns the type of the GATLocation * * The function @c GATLocation_GetType always returns GATType_GATLocation. * * @param object The object to inspect * * @return returns always @c #GATType_GATLocation. */ GATType GATLocation_GetType(GATLocation_const location); /* GATAdvertiseable API */ #define GATLOCATION_VERSION1 0x0100 #define GATLOCATION_LASTVERSION GATLOCATION_VERSION1 #define GATLOCATION_MINOR_MASK 0x00ff /** GATResult GATLocation_Serialise(GATLocation file, GATObject stream, GATBool clear_dirty) * @brief Serialise a GATLocation object * * The function GATLocation_Serialise serialises the given GATLocation object * into the given stream. * * @param object The GATLocation object to serialise. * @param stream The stream interface to use for the serialisation. * @param clear_dirty If the clear_dirty parameter is set to GATTrue, the * internal dirty flag of this object is to be reset (no used here) * * @return An error code. */ GATResult GATLocation_Serialise(GATLocation object, GATObject stream, GATBool clear_dirty); /** GATLocation GATLocation_DeSerialise(GATContext context, GATObject stream, GATBool clear_dirty) * @brief De-serialise a GATLocation object * * The function GATLocation_DeSerialise de-serialises a streamed GATLocation * object from the given stream It constructs a new instance of the * de-serialised object. * * @param context The GAT context to be used for object construction. * @param stream The stream interface to use for the serialisation. * @param result The pointer to a variable, which receives the status code of * the operation. * * @return The newly constructed GATLocation object. */ GATLocation GATLocation_DeSerialise(GATContext context, GATObject stream, GATResult *result); /** GATLocation_GetIsDirty * * The function GATLocation_GetIsDirty retrieves the status of the dirty flag * of this GATLocation object. * * @param object The GATLocation object to inspect for its dirty status. * @param isdirty The pointer to a variable, which receives the dirty status. * * @return An error code. */ GATResult GATLocation_GetIsDirty(GATLocation_const object, GATBool *isdirty); #ifdef __cplusplus } #endif #endif /* _GATLOCATION_H_ */