Nevron Open Vision Documentation
Framework / Networking / URI
In This Topic
    URI
    In This Topic
     URI Overview

    A uniform resource identifier (URI) is a string of characters used to identify a name of a resource. URIs are used for referencing and identifying resources over a network, typically the World Wide Web, using specific protocols. Each URI is defined by a scheme specifying a concrete syntax and protocol, for example "http" scheme, "ftp" scheme, "mailto" scheme, "data" scheme and so on. The most commonly used URI types are the Uniform Resource Locator (URL), informally known as web address and the data URI, which is typically used to embed binary data like images in text based documents (HTML, XML, etc.). Nevron Open Vision provides classes for working with both of these commonly used URI types, but before looking at them in details, let's see what an URI is made of.

     URI Structure
    Generic URI Syntax
    Copy Code
    <scheme name> : <hierarchical part> [ ? <query> ] [ # <fragment> ]
    

    Here's an example to a specific web resource:

    URI Example
    Copy Code
    http://www.nevron.com/documentation/framework/uri.html#uri-structure
    

    The given example defines the following URI parts:

    • Scheme: http
    • Hierarchical path
      • host: www.nevron.com
      • path: documentation/framework/uri.html
    • Fragment: uri-structure

    This information instructs an application that the file"uri.html" is located in the given path at the specified host and can be accessed through the "HTTP" protocol. The fragment part in the context of web pages is typically used to denote a specific section of the page, in this case the "uri-structure" section. This is an absolute URI, i.e. an URI which fully defines a resource. You may also meet relative URIs, which define only a part of the path to a resource and only have a meaning in the context of an absolute URI, called base URI. In order to access the resource the relative URI should be combined with the base URI to produce a new absolute URI, a process known as URI resolution.

     Creating URIs

    In your applications you will generally receive URIs as strings. In order to convert them to objects you can work with, you should first use the NUriBase class to parse them to an URI object. The NUriBase class in NOV is the base class for all URIs like URLs and data URIs. You can use its static TryCreate method to parse a string to an URI. The URI kind parameter lets you specify whether the string should be parsed as an absolute URI, as a relative URI or as whatever URI type possible (absolute or relative). The method returns true on successful parsing and the resulting URI is returned as an out parameter.

    Parsing an URI
    Copy Code
    NUriBase nUri;
    if (NUriBase.TryCreate(uri, ENUriKind.Absolute, out nUri))
    {
        // The string has been successfully parsed to an absolute URI
    }
    

    When the URI is created you can use its Scheme property or the shortcut properties for the most commonly used URI types - IsData ("data" scheme), IsHttp ("http" and "https" schemes) and IsFile ("file" scheme) to see its type. You can then cast the URI base object to an URI of a specific type like NUri for file and HTTP URIs and to NDataUri for data URIs in order to get access to properties and methods specific for that URI type.

    If you have an absolute and a relative URI, you can use the TryCombine method to resolve the relative URI, i.e. to concatenate it with the base URI:

    Combining URIs
    Copy Code
    NUriBase resultUri;
    if (NUriBase.TryCombine(baseUri, relativeUri, out resultUri))
    {
        // The URIs have been successfully combined
    }
    

    This method can be used for both web (HTTP/HTTPS) and local (FILE) URIs.

     Web and File URIs

    Web and file URIs are represented by the NUri class in NOV. It provides properties for accessing the parts of the URI, such as the host name, the port, the path, query and fragment for web URIs. The NUri class also provides static method for creating and resolving URIs:

    • TryCombine - combines an absolute URI (base) with a relative URI
    • TryResolve - first tries to create an absolute URI from a given string, but if the string represents a relative URI combines it with the given absolute URI (base) in order to resolve it

    For file URIs a useful property LocalPath that can be used to get a local operating system representation is provided. The LocalPathLocation property indicates whether Windows or Unix notation is used in the file URI.

     Data URIs

    The NDataUri class provides methods and properties for working with data URIs. Besides as a result of the TryCreate method of the NDataUri base class you can create data URI instances using the static FromImage methods of the NDataUri class. They help you easily create data URIs for embedding in XML, HTML or other text documents. When the data URI is created you can simply use its ToString method to get its string representation. The following code demonstrates how to create a data URI from an image and embed it in an HTML code fragment:

    Creating of Data URI
    Copy Code
    NDataUri dataUri = NDataUri.FromImage(image);
    string htmlImage = "<img src=\"" + dataUri.ToString() + "\" />";
    
    The MimeType of the data URI indicates the type of data the data URI contains and the Data property gives you access to the raw data of the data URI as a byte array.
     Local File URIs

    Local file URIs in NOV are represented by the NFileUri class.

    The following is an example for a local file URI: file:///D:/MyPhoto.jpg

    It provides the following properties and methods:

    • IsAbsolute - checks whether the file URI represents an absolute file path.
    • Path - gets the local path of the file URI in the current platform's notation.
    • GetLocalPath - gets the local path of the file URI in the current platform's notation.
    • GetLocalPath(notation) - gets the local path of the file URI in the given notation (Windows or Unix).

    NFileUri implements the INDomCustomSerializable interface, so NFileUri instances can easily be serialized/deserialized by NOV.

    See Also