/MEng/System/Runtime/URL

ClassPath: MEng.System.Runtime.URL
Parent ClassPath: MEng.Object
Copyable: Yes
Final: Yes
MEng.System.Runtime.URL represents a standard network Universal Resource Locator. It allows you to parse and build URLs and to escape them as required by network rules and to expand incoming escaped URLs to their internal format.
Note that, because of the effective impossibility of figuring out how to escape the contents of a raw URL string (because it can be filled with ambiguities), it is a assumed that any URLs you build up yourself are built from pre-escaped content. I.e. the internal state of the content inside the URL class is escaped, and you must provide any content that way. When you set a URL on this class to be parsed and internalized, it is assumed that this is a URL coming in from the outside with all the escapes in place.

Nested Classes:
Enum=URLErrors
    EncodingError   : "";
    QueryError      : "";
    SetError        : "";
EndEnum;
This enumerated type defines the errors that are thrown by this class. Some of them have no text because it will just be set to the text of the underlying C++ error that is really being reported.
Enum=URLComps
    Path     : "Path";
    Query    : "Query";
    Fragment : "Fragment";
EndEnum;
This enumerated type is used in some places where it is necessary to refer to a particular part of the URL, not the whole URL content.
Enum=URLProtos
    None   : "None";
    File   : "File";
    HTTP   : "HTTP";
    FTP    : "FTP";
    MailTo : "MailTo";
    News   : "News";
EndEnum;
This enumerated type is used to represent the URL protocols understood by this class. The None entry is used to indicate no protocol is desired or has been set.
Constructors:
Constructor();
Their is only a default constructor available.
Final, Const Methods:
Encode
(
    [In]    MEng.String  ToEncode
    , [Out] MEng.String  ToFill
    , [In]  URLComps     Component
    , [In]  MEng.Boolean Append
)   Returns MEng.Boolean;
Encodes the ToEncode string into the ToFill string, using the encoding rules for the URL components indicated in the Component parameter. There are different rules in the different URL components. The Append parameter indicates whether you want the result to be append to ToFill or to overwrite its current contents.
Note that when using the Query component, this does not mean it will take an entire query string and encode it. It assumes you are passing in a single key or value to be encoded. The rules are just too complex to try to figure out a full query string and always get it right because you can have query separator characters anywhere in that string, and there's no way to know which are real ones and which should be escaped.
Expand
(
    [In]    MEng.String  ToExpand
    , [Out] MEng.String  ToFill
    , [In]  URLComps     Component
    , [In]  MEng.Boolean Append
)   Returns MEng.Boolean;
Expands an encoded URL component in ToEncode into the ToFill string, using the encoding rules for the URL components indicated in the Component parameter. There are different rules in the different URL components. The Append parameter indicates whether you want the result to be append to ToFill or to overwrite its current contents.
Unlike with Encode above, there are no ambiguities when going in this direction (as long as the input is valid), so you can pass an entire query string in and have it expanded.
GetEncoded([Out] MEng.String ToFill);
Fills in the ToFill string with the fully encoded form of the URL, i.e. all the components that have been set on this URL object are formatted out and all escaping done.
GetEncodedParts
(
    [Out]   MEng.String  Proto
    , [Out] MEng.String  User
    , [Out] MEng.String  Host
    , [Out] MEng.String  Path
    , [Out] MEng.String  Suffix
);
Returns all of the components of the URL (which have been set) in their encoded forms. Any that have not been set will be empty.
GetFullText([Out] MEng.String ToFill);
Fills in the ToFill string with the fully expanded form of the URL, i.e. all the components that have been set on this URL are formatted out and all escaped characters are expanded.
GetPort() Returns MEng.Card4;
Returns the port currently indicated in the URL. The port will be set explicitly if a URL string is set on this object, since the port will be set to the default for the indicated protocol (if any is present), or if a port is explicitly present in the set URL string. If has not been set explicitly or implicitly, then it will be zero (which is never legal.)
GetProto() Returns URLProtos;
Returns the name of the protocol set on this URL, if any. If none has been set, then the None value is returned.
Final, Non-Const Methods:
Clear();
Resets this URL object to an empty state.
Set([In] MEng.String ToSet, [In] BaseInfo.FQTypes Type);
Set2([In] MEng.String Base, [In] MEng.String Rel);
Set3([In] URL Base, [In] MEng.String Rel);
These methods all build up a URL from either a fully or partially qualified URL string, from a base string plus a partially qualified URL string, or from a base URL object plus a partially qualified URL string. In the first case, you can indicate whether you expect the incoming text to be a fully qualified URL (i.e. starting from the protocol) or a partially qualified URL, or that you don't care which. If you indicate fully or partially qualified, and the incoming string is not of that type, then the SetError exception will be thrown.
In the latter two cases, the Rel text must be a relatively qualified URL, i.e. it must start at the path level and that path must not start with a / character, because it's going to be grafted onto the base URL text or base URL object to create a new URL. The base text may or may not be fully qualified, but if it doesn't have at least a path component, the result may not be correct. all parts of the base URL object up to the path component are used. The partial path component and any query or fragment of the relative text are used.

ClassPath:	MEng.System.Runtime.URL
Parent ClassPath:	MEng.Object
Copyable:	Yes
Final:	Yes