category: Specification <notextile> <h2> <a href="#contents" name="document_status">Document status</a> </h2> <p /> <table class="noborder" border="0" cellspacing="2" cellpadding="0"> <tr valign="top"> <td align="right"><font size="-1">Date:</font></td> <td><font size="-1"><strong>16-Mar-2001</strong></font></td> </tr> <tr valign="top"> <td align="right"><font size="-1">Document number:</font></td> <td><font size="-1"><strong>2501,846/FS</strong></font></td> </tr> <tr valign="top"> <td align="right"><font size="-1">Change number:</font></td> <td><font size="-1"><strong>ECO 4428</strong></font></td> </tr> <tr valign="top"> <td align="right"><font size="-1">Master format:</font></td> <td><font size="-1"><strong>HTML</strong></font></td> </tr> <tr valign="top"> <td align="right"><font size="-1">Issue:</font></td> <td><font size="-1"><strong>3</strong></font></td> </tr> <tr valign="top"> <td align="right"><font size="-1">Last release:</font></td> <td><font size="-1"><strong>2</strong></font></td> </tr> <tr valign="top"> <td align="right"><font size="-1">Associated project:</font></td> <td><font size="-1"><strong>310 "STB-400"</strong></font></td> </tr> <tr valign="top"> <td align="right" valign="top"><font size="-1">Authors:</font></td> <td><font size="-1"><strong>A.Hodgkinson</strong></font></td> </tr> <tr valign="top"> <td align="right"><font size="-1">Status:</font></td> <td><font size="-1"><strong>Confidential (secret)<br />© Pace Micro Technology plc</strong></font></td> </tr> </table> <p /> Modified for RISC OS Open Limited Wiki by ADH, 30-May-2007. Revised 24-Mar-2011. Layout-related changes only, except for removal for redundant external links. <p /> <h2> <a href="#contents" name="foreword">Foreword</a> </h2> <p /> Software on the <acronym title="Set top box">STB</acronym> 400 often needs to find out if a given uniform resource locator - <acronym title="uniform resource locator">URL</acronym> <a href="#ref1">[1]</a>, <a href="#ref2">[2]</a>, <a href="#ref3">[3]</a> - meets some comparison criteria in order to perform different behaviour depending on the <acronym>URL</acronym> in use. For example, a match may activate various extensions in the web browser depending on the page being fetched or lead to selection of a certain protocol module for video playback. <i>Check URL</i> provides a central interface through which its clients may perform this task. <p /> <h2> <a href="#contents" name="acknowledgements">Acknowledgements</a> </h2> <p /> © Pace Micro Technology plc. All trademarks are acknowledged. <p /> <h2> <a href="#contents" name="contents">Contents</a> </h2> <p /> <ol type="1"> <li><strong><a href="#foreword">Foreword</a></strong> <li><strong><a href="#acknowledgements">Acknowledgements</a></strong> <li><strong><a href="#contents">Contents</a></strong> <li><strong><a href="#audience">Audience</a></strong> <p /> <li><strong><a href="#overview">Overview</a></strong> <li><strong><a href="#outstanding_issues">Outstanding issues</a></strong> <li><strong><a href="#file formats">File formats</a></strong> <p /> <li><strong><a href="#programmer_interface">Programmer interface</a></strong> <p /> <em><a href="#swi_checkurl_check">CheckURL_Check</a></em><br /> <em><a href="#swi_checkurl_readareaid">CheckURL_ReadAreaID</a></em><br /> <em><a href="#swi_checkurl_readfile">CheckURL_ReadFile</a></em><br /> <em><a href="#swi_checkurl_addarea">CheckURL_AddArea</a></em><br /> <em><a href="#swi_checkurl_deletearea">CheckURL_DeleteArea</a></em> <p /> <li><strong><a href="#errors">Check URL errors</a></strong> <li><strong><a href="#dependencies">Dependencies</a></strong> <p /> <li><strong><a href="#performance_targets">Performance targets</a></strong> <li><strong><a href="#development_test_strategy">Development test strategy</a></strong> <li><strong><a href="#acceptance_criteria">Acceptance criteria</a></strong> <p /> <li><strong><a href="#appendix A">Appendix A: Example area ID cacheing code</a></strong> <p /> <li><strong><a href="#history">History</a></strong> <li><strong><a href="#references">References</a></strong> </ol> <p /> <h2> <a href="#contents" name="audience">Audience</a> </h2> <p /> This document is aimed at a technical audience intending to incorporate calls to <i>Check URL</i> in client software. <p /> <h2> <a href="#contents" name="overview">Overview</a> </h2> <p /> <i>Check URL</i> matches a given <acronym>URL</acronym> against one or many <acronym>URL</acronym> <dfn>fragments</dfn> and reports whether or not there is a match. The fragments can lead to matches based on complete host names or partial domains, ports, and paths. The fragments can be supplied in a central configuration file read at module initialisation (in <acronym>RAM</acronym> builds) or given to the module at run-time. <p /> Matches are searched for within an <dfn>area</dfn> and only <acronym>URL</acronym> fragments within that area will be checked. This allows many different applications to use <i>Check URL</i> simultaneously. It also allows them to share their required fragments within one <i>Check URL</i> configuration file, though they may dynamically add and remove areas if they wish. <p /> Client software decides what area titles to use. It is strongly recommended that area titles are based on the software's allocated name, an underscore, then any more specific title that the client may wish to associate. This helps avoid area namespace collision (for example, <tt>VideoControl_ProtocolModules</tt>). <p /> <h2> <a href="#contents" name="outstanding_issues">Outstanding issues</a> </h2> <p /> There are no outstanding issues at present. <p /> <h2> <a href="#contents" name="file_formats">File formats</a> </h2> <p /> Fragment and area descriptions can be provided in a central configuration file as well as dynamically. The configuration file is read from <tt>Choices:CheckURL</tt> at module initialisation in <acronym>RAM</acronym> builds or just before the first <i>Check URL</i> <acronym>SWI</acronym> is invoked after initialisation in <acronym>ROM</acronym> builds. The file is plain text; LF or CR are taken as line endings, and blank lines are ignored (so <acronym>DOS</acronym> style text files will work fine). All other white space is treated as a field separator. The body of each area within the file is based on two fields; one describes hosts, domains, or partial <acronym>URL</acronym>s (without any fetch scheme specified) and the other gives a parameter string. <p /> If <em>at the start of a new line</em> a hash character is encountered, the line is treated as a comment and the sectionNumberingContents are ignored save for scanning for a subsequent LF or CR character marking the start of the next line. Otherwise, the data is treated as the host, domain or <acronym>URL</acronym> fragment: <p /> <ol type="1"> <li>If the item starts with a dot, '.', then the right hand side of any domain will match (e.g. <tt>.co.uk</tt> will match <tt>pace.co.uk</tt>, <tt>this.that.co.uk</tt>, but not <tt>this.org.uk</tt> or <tt>this.co.uk.that</tt>). <li>If the item does not start with a dot, then the whole domain must match (e.g. <tt>pace.co.uk</tt> will match <tt>pace.co.uk</tt> but not <tt>video.pace.co.uk</tt>). <li>If a specific port specifier is to be looked for, rather than any port, include it in the usual fashion with a colon after the domain or domain fragment (e.g. <tt>.pace.co.uk:5000</tt>). <li>If the item has a forwards slash character in, '/', then in addition to matching the domain as described above, the left hand side of the path is matched too (e.g. <tt>.co.uk/this/</tt> will match <tt>pace.co.uk/this/that.mpi</tt> as well as <tt>pace.co.uk/this/</tt> but not <tt>pace.co.uk/that/</tt>; in addition, <tt>.co.uk/this</tt> will match <tt>video.co.uk/this/that.mpi</tt> as well as <tt>video.drome.co.uk/thistoo/</tt>). </ol> <p /> After any amount of white space not including CR or LF, <i>Check URL</i> expects to see a <dfn>parameter</dfn> string. This is any combination of characters terminated by CR and LF. When clients find a match, this string (NUL terminated) is given back as part of the match details. Clients can thus encode any information they need statically associated with the match fragment in this parameter string. <p /> If a parameter string is not seen, the data read thus far is assumed to be an area name instead of a <acronym>URL</acronym> fragment. Consequently area titles cannot contain white space. If you do not want to associate any parameter string with a URL, just include (say) a single non-white space character as a place holder; for example, a single hyphen. <p /> The number of fragments, the length of those fragments and the length of their parameter strings is limited by available memory only. The length of an area title is also limited by available memory only. The internal usage of area IDs limits the number of areas to 2<sup>24</sup>, memory permitting. <p /> Within each area, matches are carried out from the bottom up. Put the most specific matches, if required, last, and the most general matches first. For example, you may wish to match a path of <tt>/this/specific/path/</tt> for one thing, otherwise match <tt>/this/</tt> for everything else - in that case put the more general rule first in the file. <p /> All string matches, without exception, are case-sensitive. <p /> Whenever an attempt to open a file in <i>Check URL</i> fails when a <acronym>SWI</acronym> requires it, <a href="#errors">error &818601</a> is generated. This isn't raised if the central configuration file can't be opened at module initialisation. If the format of any file appears to be invalid, <a href="#errors">error &818602</a> is generated. This <em>does</em> include the central configuration file. <p /> <dl> <dt>Example <dd><p /> <pre># Video Control protocol module selection. VideoControl_ProtocolModules jupiter.eng.acorn.co.uk 53580 .eng.acorn.co.uk/testvideos/ 53540 .eng.acorn.co.uk/testvideos/2/ 535C0 # JavaScript video control extension security. NCFresco_JavaScript_VideoSecurity webpool.isp.com - users.isp.com -</pre> </dl> <p /> <h2> <a href="#contents" name="programmer_interface">Programmer interface</a> </h2> <p /> <table width="100%" border="0"> <tr bgcolor="#e5e5e5"> <td align="right"> <font size="+1"><a href="#contents" name="swi_checkurl_check">CheckURL_Check</a></font> </td> </tr> <tr> <td align="right">(SWI &54140)</td> </tr> </table> <p /> See if a <acronym>URL</acronym> matches any fragments. <p /> <dl> <dt>On entry <dd><p /> <table border="0" cellspacing="0" cellpadding="0"> <tr valign="top"> <td>R0</td><td>=</td> <td> Flags:<br /> <table border="0" cellspacing="0" cellpadding="0"> <tr valign="top" align="left"> <th>Bit(s)</th> <th> </th> <th>Meaning</th> </tr> <tr valign="top"> <td>0</td> <td> </td> <td> If clear, R1 is a pointer to a NUL-terminated area name string. If set, R1 is an area ID </td> </tr> <tr valign="top"> <td>1</td> <td> </td> <td> If clear, R1 is a pointer to a NUL-terminated <acronym>URL</acronym> string. If set, R1 is a pointer to a <acronym>URL</acronym> descriptor block </td> </tr> <tr valign="top"> <td>2-31</td> <td> </td> <td>Reserved (must be zero)</td> </tr> </table> </td> </tr> <tr valign="top"> <td>R1</td> <td>=</td> <td> Pointer to a NUL-terminated area name string if R0:0 clear, else an area ID </td> </tr> <tr valign="top"> <td>R2</td> <td>=</td> <td> Pointer to a NUL-terminated <acronym>URL</acronym> string if R0:1 clear, else pointer to a <acronym>URL</acronym> descriptor block </td> </tr> </table> <p /><dt>On exit <dd><p /> <table border="0" cellspacing="0" cellpadding="0"> <tr valign="top"> <td>R0</td><td>=</td> <td> Flags:<br /> <table border="0" cellspacing="0" cellpadding="0"> <tr valign="top" align="left"> <th>Bit(s)</th> <th> </th> <th>Meaning</th> </tr> <tr valign="top"> <td>0</td> <td> </td> <td> If set, there is a match (R1 is valid). If clear, there is no match and R1 is preserved </td> </tr> <tr valign="top"> <td>1-31</td> <td> </td> <td>Reserved (must be zero)</td> </tr> </table> </td> </tr> <tr valign="top"> <td>R1</td> <td>=</td> <td> Pointer to the parameter string associated with the matched fragment, NUL terminated, if R0:0 on exit is set, else preserved </td> </tr> </table> <p /> All other registers preserved. <p /><dt>Interrupts <dd><p />Interrupt state is undefined. <p /><dt>Re-entrancy <dd><p /><acronym>SWI</acronym> is not re-entrant. <p /><dt>Use <dd><p /> This <acronym>SWI</acronym> checks a given <acronym>URL</acronym> against any fragments listed in the given area. The area may be specified as a string or as a numeric ID (see <acronym>SWI</acronym> <a href="#swi_checkurl_readareaid">CheckURL_ReadAreaID</a>). Using an ID is faster as the area name string doesn't have to be matched to find the fragments. The <acronym>URL</acronym> may be specified as either a normal NUL-terminated string, or if the client has had cause to pass it through the <i>URL Fetcher</i> <a href="#ref4">[4]</a> module, it can give a pointer to a descriptor block as filled in by <acronym>SWI</acronym> URL_ParseURL 1. If the client already has this information, it stops <i>Check URL</i> having to claim memory and spend time splitting the <acronym>URL</acronym> up again. <p /> If the area given is invalid or cannot be found, <a href="#errors">error &818600</a> is returned. <p /><dt>Related <acronym>SWI</acronym>s <dd><p /><a href="#swi_checkurl_readareaid">CheckURL_ReadAreaID</a> <p /><dt>Related vectors <dd><p />None </dl> <p /> <table width="100%" border="0"> <tr bgcolor="#e5e5e5"> <td align="right"> <font size="+1"><a href="#contents" name="swi_checkurl_readareaid">CheckURL_ReadAreaID</a></font> </td> </tr> <tr> <td align="right">(SWI &54141)</td> </tr> </table> <p /> Find out the quick reference ID for a given area name string or vice versa. <p /> <dl> <dt>On entry <dd><p /> <table border="0" cellspacing="0" cellpadding="0"> <tr valign="top"> <td>R0</td><td>=</td> <td> Flags:<br /> <table border="0" cellspacing="0" cellpadding="0"> <tr valign="top" align="left"> <th>Bit(s)</th> <th> </th> <th>Meaning</th> </tr> <tr valign="top"> <td>0</td> <td> </td> <td> If clear, R1 on entry holds a pointer to a NUL-terminated area name string and on exit holds an area ID if the name is recognised. If set, R1 on entry holds an area ID and on exit points to a NUL-terminated area name string if the ID is recognised </td> </tr> <tr valign="top"> <td>1-31</td> <td> </td> <td>Reserved (must be zero)</td> </tr> </table> </td> </tr> <tr valign="top"> <td>R1</td> <td>=</td> <td> Pointer to a NUL-terminated area name string if R0:0 clear, else an area ID </td> </tr> </table> <p /><dt>On exit <dd><p /> <table border="0" cellspacing="0" cellpadding="0"> <tr valign="top"> <td>R0</td><td>=</td> <td> Flags All bits currently reserved (must be zero) </td> </tr> <tr valign="top"> <td>R1</td><td>=</td> <td> An area ID if R0:0 on entry was clear, else pointer to a NUL-terminated area name string </td> </tr> </table> <p /> All other registers preserved. <p /><dt>Interrupts <dd><p />Interrupt state is undefined. <p /><dt>Re-entrancy <dd><p /><acronym>SWI</acronym> is not re-entrant. <p /><dt>Use <dd><p /> This call is used to convert between an area name string and an area ID and back again. It is quicker to use area IDs in calls that take an ID or a string in order to find associated fragments since the ID references the fragments directly. Clients <strong>must</strong> treat area IDs as opaque values. <p /> If the area given is invalid or cannot be found, <a href="#errors">error &818600</a> is returned. <p /> An area ID is in practice composed of two parts; a 24-bit array index leading to the 2<sup>24</sup> area limit and an 8-bit counter. An internal array holds pointers to the area fragments along with an associated counter. When an area is deleted its position in the array may be re-used later, but the counter is incremented. This way, if a stale area ID is used by a client the mismatch of the counter will let <i>Check URL</i> determine that the ID is no longer valid. A similar system is used for task handles in the Window Manager. Clients can take an area ID, cache it, and hold this for all time, but if they do so they risk the ID becoming stale. If somebody else was to delete and recreate the area the ID would change. To be completely robust, code should cache the ID and attempt to re-cache once if the ID subsequently fails. <a href="#appendix A">Appendix A</a> contains example code. <p /> An area ID of zero is guaranteed to be invalid. <p /><dt>Related <acronym>SWI</acronym>s <dd><p /> <a href="#swi_checkurl_check">CheckURL_Check</a><br /> <a href="#swi_checkurl_addarea">CheckURL_AddArea</a><br /> <a href="#swi_checkurl_deletearea">CheckURL_DeleteArea</a> <p /><dt>Related vectors <dd><p />None </dl> <p /> <table width="100%" border="0"> <tr bgcolor="#e5e5e5"> <td align="right"> <font size="+1"><a href="#contents" name="swi_checkurl_readfile">CheckURL_ReadFile</a></font> </td> </tr> <tr> <td align="right">(SWI &54142)</td> </tr> </table> <p /> Read a new configuration file. <p /> <dl> <dt>On entry <dd><p /> <table border="0" cellspacing="0" cellpadding="0"> <tr valign="top"> <td>R0</td><td>=</td> <td> Flags: All bits currently reserved (must be zero) </td> </tr> <tr valign="top"> <td>R1</td><td>=</td><td>Pointer to NUL-terminated filename string</td> </tr> </table> <p /><dt>On exit <dd><p /> <p /> All registers preserved. <p /><dt>Interrupts <dd><p />Interrupt state is undefined. <p /><dt>Re-entrancy <dd><p /><acronym>SWI</acronym> is not re-entrant. <p /><dt>Use <dd><p /> This <acronym>SWI</acronym> allows clients to give <i>Check URL</i> a new configuration file in the same format as the main file described in the <a href="#file formats">File formats</a> section. Usually a client will have called <a href="#swi_checkurl_deletearea">CheckURL_DeleteArea</a> beforehand to remove any current areas, though this is not necessary. In the event that an area is already present with the same name as in the new file, fragments will be added. Any duplicates will not be stripped out. Items added will be checked before the items already in the area, with bottom-up matching within the file itself (as for the main configuration file). For example, if <i>Check URL</i> already holds an area from reading the following file: <p /> <pre>VideoControl_ProtocolModules / 53580 .eng.acorn.co.uk/testvideos/ 53540</pre> <p /> and a client attempts to load this file: <p /> <pre>VideoControl_ProtocolModules / 53A00 /multicast 53540</pre> <p /> the result is the same as loading the following in one go: <p /> <pre>VideoControl_ProtocolModules / 53580 .eng.acorn.co.uk/testvideos/ 53540 / 53A00 /multicast 53540</pre> <p /> So with bottom-up matching, the <tt>/</tt> entry for <tt>53580</tt> would never get matched. <p /> Adding new areas or adding new fragments to existing areas does not alter the validity of area IDs. <p /><dt>Related <acronym>SWI</acronym>s <dd><p /> <a href="#swi_checkurl_addarea">CheckURL_AddArea</a><br /> <a href="#swi_checkurl_deletearea">CheckURL_DeleteArea</a> <p /><dt>Related vectors <dd><p />None </dl> <p /> <table width="100%" border="0"> <tr bgcolor="#e5e5e5"> <td align="right"> <font size="+1"><a href="#contents" name="swi_checkurl_addarea">CheckURL_AddArea</a></font> </td> </tr> <tr> <td align="right">(SWI &54143)</td> </tr> </table> <p /> Add a new area, or a fragment to an existing area. <p /> <dl> <dt>On entry <dd><p /> <table border="0" cellspacing="0" cellpadding="0"> <tr valign="top"> <td>R0</td><td>=</td> <td> Flags:<br /> <table border="0" cellspacing="0" cellpadding="0"> <tr valign="top" align="left"> <th>Bit(s)</th> <th> </th> <th>Meaning</th> </tr> <tr valign="top"> <td>0</td> <td> </td> <td> If clear, R1 is a pointer to a NUL-terminated area name string. If set, R1 is an area ID </td> </tr> <tr valign="top"> <td>1</td> <td> </td> <td> If clear, R2 is a pointer to a NUL-terminated set of CR or LF separated fragments and parameter pairs. If set, R2 is a pointer to a NUL-terminated filename string </td> </tr> <tr valign="top"> <td>2-31</td> <td> </td> <td>Reserved (must be zero)</td> </tr> </table> </td> </tr> <tr valign="top"> <td>R1</td><td>=</td> <td> A NUL-terminated area name string if R0:0 clear, else an area ID </td> </tr> <tr valign="top"> <td>R2</td> <td>=</td> <td> Pointer to a NUL-terminated set of CR or LF separated fragments and parameter pairs if R0:1 clear, else pointer to a NUL-terminated filename string; zero if no fragments are to be added to the area at this time </td> </tr> </table> <p /><dt>On exit <dd><p /> <table border="0" cellspacing="0" cellpadding="0"> <tr valign="top"> <td>R1</td><td>=</td> <td> Area ID of the (possibly new) area in use. </td> </tr> </table> <p /> All other registers preserved. <p /><dt>Interrupts <dd><p />Interrupt state is undefined. <p /><dt>Re-entrancy <dd><p /><acronym>SWI</acronym> is not re-entrant. <p /><dt>Use <dd><p /> This <acronym>SWI</acronym> is used to add new areas or add fragments to existing areas. If called with an area ID or name that is unknown, a new area is created, else any fragments given are merged into the existing area in exactly the same way as described for <acronym>SWI</acronym> <a href="#swi_checkurl_readfile">CheckURL_ReadFile</a>. <p /> Fragments may be supplied directly, as a single string holding what amounts to the fragment definition part of a configuration file, or in a file containing the same data. The format in both cases is basically the same as for the main configuration file but just describes one area, and so must contain no area names. If the <acronym>SWI</acronym> is given a string holding match fragments directly but the format appears to be invalid, <a href="#errors">error &818603</a> is returned. <p /> The return value in R1 allows clients creating new areas by name to avoid making a subsequent call to <acronym>SWI</acronym> <a href="#swi_checkurl_readareaid">CheckURL_ReadAreaID</a> if they want to refer to the area by ID in future. <p /><dt>Related <acronym>SWI</acronym>s <dd><p /> <a href="#swi_checkurl_readfile">CheckURL_ReadFile</a><br /> <a href="#swi_checkurl_deletearea">CheckURL_DeleteArea</a> <p /><dt>Related vectors <dd><p />None </dl> <p /> <table width="100%" border="0"> <tr bgcolor="#e5e5e5"> <td align="right"> <font size="+1"><a href="#contents" name="swi_checkurl_deletearea">CheckURL_DeleteArea</a></font> </td> </tr> <tr> <td align="right">(SWI &54144)</td> </tr> </table> <p /> Remove one or all areas. <p /> <dl> <dt>On entry <dd><p /> <table border="0" cellspacing="0" cellpadding="0"> <tr valign="top"> <td>R0</td><td>=</td> <td> Flags:<br /> <table border="0" cellspacing="0" cellpadding="0"> <tr valign="top" align="left"> <th>Bit(s)</th> <th> </th> <th>Meaning</th> </tr> <tr valign="top"> <td>0</td> <td> </td> <td> If clear, delete the area specified in R1. If set, delete all areas </td> </tr> <tr valign="top"> <td>1</td> <td> </td> <td> If clear, R1 is a pointer to a NUL-terminated area name string. If set, R1 is an area ID </td> </tr> <tr valign="top"> <td>2-31</td> <td> </td> <td>Reserved (must be zero)</td> </tr> </table> </td> </tr> <tr valign="top"> <td>R1</td><td>=</td> <td> If R0:0 set, ignored. If R0:0 and R0:1 clear, pointer to a NUL-terminated area name string. If R0:0 clear and R0:1 set, an area ID </td> </tr> </table> <p /><dt>On exit <dd><p /> All registers preserved. <p /><dt>Interrupts <dd><p />Interrupt state is undefined. <p /><dt>Re-entrancy <dd><p /><acronym>SWI</acronym> is not re-entrant. <p /><dt>Use <dd><p /> This call deletes an area based on its name or ID, or will delete all areas if R0:0 is set. Any area ID relating to a deleted area will become invalid immediately. <p /> If R0:0 is clear and the area given in R1 is invalid or cannot be found, <a href="#errors">error &818600</a> is returned. <p /><dt>Related <acronym>SWI</acronym>s <dd><p /> <a href="#swi_checkurl_readfile">CheckURL_ReadFile</a><br /> <a href="#swi_checkurl_addarea">CheckURL_AddArea</a> <p /><dt>Related vectors <dd><p />None </dl> <p /> <h2> <a href="#contents" name="errors">Check URL errors</a> </h2> <p /> The <i>Check URL</i> module is allocated one error block at &818600: <p /> <table align="center" width="85%" cellspacing="1" cellpadding="2" border="1" bgcolor="#ffffff"> <tr valign="top" bgcolor="#dddddd"><th>Error no.</th><th>Meaning</th></tr> <tr valign="top"> <td>&818600</td> <td> <tt>Area not known</tt><br /> A client has passed an unknown area name string or ID to <acronym>SWI</acronym> <a href="#swi_checkurl_check">CheckURL_Check</a>, <a href="#swi_checkurl_readareaid">CheckURL_ReadAreaID</a>, or <a href="#swi_checkurl_deletearea">CheckURL_DeleteArea</a>. </td> </tr> <tr valign="top"> <td>&818601</td> <td> <tt>Cannot open configuration file</tt><br /> An attempt to open a configuration file has failed. This is only raised in response to any <acronym>SWI</acronym> that calls for a file to be read. </td> </tr> <tr valign="top"> <td>&818602</td> <td> <tt>Invalid configuration file</tt><br /> Raised whenever <em>any</em> file read by <i>Check URL</i> is of an apparently invalid format. This includes finding an area name field if a file is read in <acronym>SWI</acronym> <a href="#swi_checkurl_addarea">CheckURL_AddArea</a>. </td> </tr> <tr valign="top"> <td>&818603</td> <td> <tt>Invalid fragments</tt><br /> The URL fragments and parameters string given to <acronym>SWI</acronym> <a href="#swi_checkurl_addarea">CheckURL_AddArea</a> is of an apparently invalid format (for example, a fragment may be missing a parameter). </td> </tr> <tr valign="top"> <td>&818604</td> <td> <tt>Check URL could not claim enough memory</tt><br /> Memory was exhausted during some allocation operation being performed by <i>Check URL.</i> </td> </tr> </table> <p /> <h2> <a href="#contents" name="dependencies">Dependencies</a> </h2> <p /> For <acronym>URL</acronym> canonicalisation, <i>Check URL</i> will call the URL_ParseURL <acronym>SWI</acronym> and thus <i>URL Fetcher</i> 0.43 or later must be present. <p /> <h2> <a href="#contents" name="performance_targets">Performance targets</a> </h2> <p /> Final code size of the version described by this document should be inside 24K. Memory claimed will depend on the number of areas and their fragments and parameters, and the lengths of the strings involved. No memory will be claimed at run-time if all areas are deleted. Since area IDs work as indices into an array of pointers, the array itself may remain at a high water mark size if an area sits at the top of the array even after all others are deleted; however, once that area is removed the whole array will be freed. <p /> <h2> <a href="#contents" name="development_test_strategy">Development test strategy</a> </h2> <p /> The <acronym>SWI</acronym> interface will be tested to ensure it performs as documented in a debug build, with various combinations of valid and invalid configuration files or configuration file fragments. <p /> <h2> <a href="#contents" name="acceptance_criteria">Acceptance criteria</a> </h2> <p /> The <acronym>SWI</acronym>s must perform as documented and the <a href="#performance targets">performance targets</a> must be met. <p /> <h2> <a href="#contents" name="appendix_a">Appendix A: Example area ID cacheing code</a> </h2> <p /> Refering to an area by its area ID is significantly faster than referring to it by name. Multiple clients may be using <i>Check URL</i> however, and it is possible that one of them could delete and recreate an area you are using, e.g. to ensure that a known set of fragments exist in that area and no others. At this point the old ID becomes stale. Whilst you may consider it legitimate to allow this stale ID to fault depending on the nature of the client you are writing, if possible it is better to make a single attempt to re-read the ID and continue if this attempt succeeds. An example piece of C code might read as follows: <pre><font color="#008800">#include</font> <stdlib.h> <font color="#008800">#include</font> <stdbool.h> <font color="#008800">#include</font> <swis.h> <i><font color="#777777">/* This is exported via. Check URL's !MkExport */</font></i> <font color="#008800">#include</font> <CheckURL.h> <i><font color="#777777">/* Area name to use */</font></i> <font color="#008800">#define</font> AreaName "<font color="#004444">VideoControl_ProtocolModules</font>" <i><font color="#777777">/* For any URL, this can hold a more complete description than */</font></i> <i><font color="#777777">/* strings, and makes comparing two URLs in a valid manner easier. */</font></i> <b>typedef</b> <b>struct</b> url_description <b>{</b> <b>char</b> <b>*</b> full<b>;</b> <i><font color="#777777">/* Complete, canonicalised URL */</font></i> <b>char</b> <b>*</b> protocol<b>;</b> <i><font color="#777777">/* Such as 'http' or 'mailto' */</font></i> <b>char</b> <b>*</b> host<b>;</b> <i><font color="#777777">/* E.g. 'www.acorn.com' */</font></i> <b>char</b> <b>*</b> port<b>;</b> <i><font color="#777777">/* For example '8080' */</font></i> <b>char</b> <b>*</b> user<b>;</b> <i><font color="#777777">/* E.g. 'ahodgkin' */</font></i> <b>char</b> <b>*</b> password<b>;</b> <i><font color="#777777">/* E.g. 'NotMine' */</font></i> <b>char</b> <b>*</b> account<b>;</b> <i><font color="#777777">/* As in ftp://user:pass:account@host/ */</font></i> <b>char</b> <b>*</b> path<b>;</b> <i><font color="#777777">/* Speaks for itself */</font></i> <b>char</b> <b>*</b> query<b>;</b> <i><font color="#777777">/* CGI info - after a '?' in a URL */</font></i> <b>char</b> <b>*</b> fragment<b>;</b> <i><font color="#777777">/* Anchor info - after a '#' in a URL */</font></i> <b>}</b> url_description<b>;</b> <i><font color="#777777">/**************************************************************/</font></i> <i><font color="#777777">/* url_match() */</font></i> <i><font color="#777777">/* */</font></i> <i><font color="#777777">/* Match a given URL_Description in the area recorded in */</font></i> <i><font color="#777777">/* 'ConfigArea' through the Check URL module. Caches the area */</font></i> <i><font color="#777777">/* ID for speed and will attempt to re-cache if this ID */</font></i> <i><font color="#777777">/* appears to become invalid later via. a recursive call. */</font></i> <i><font color="#777777">/* */</font></i> <i><font color="#777777">/* Parameters: Pointer to the url_description to match; */</font></i> <i><font color="#777777">/* */</font></i> <i><font color="#777777">/* Pointer to a char * to take a pointer to the */</font></i> <i><font color="#777777">/* match parameter (will be NULL on exit if the */</font></i> <i><font color="#777777">/* match fails); */</font></i> <i><font color="#777777">/* */</font></i> <i><font color="#777777">/* true to support the stale ID recovery attempt */</font></i> <i><font color="#777777">/* else false. */</font></i> <i><font color="#777777">/**************************************************************/</font></i> <b>static</b> _kernel_oserror <b>*</b> url_match<b>(</b>url_description <b>*</b> d<b>,</b> <b>const</b> <b>char</b> <b>*</b><b>*</b> param<b>,</b> bool allow_fail<b>)</b> <b>{</b> <b>static</b> <b>unsigned</b> <b>int</b> area_id <b>=</b> 0<b>;</b> _kernel_oserror <b>*</b> e<b>;</b> <b>unsigned</b> <b>int</b> match<b>;</b> <b>if</b> <b>(</b>param <b>==</b> NULL<b>)</b> <b>return</b> NULL<b>;</b> <b>*</b>param <b>=</b> NULL<b>;</b> <i><font color="#777777">/* Ensure we have an area ID */</font></i> <b>if</b> <b>(</b>area_id <b>==</b> 0<b>)</b> <b>{</b> allow_fail <b>=</b> false<b>;</b> <i><font color="#777777">/* Make sure we don't try and reread it in a moment */</font></i> e <b>=</b> _swix<b>(</b>CheckURL_ReadAreaID<b>,</b> _INR<b>(</b>0<b>,</b>1<b>)</b> <b>|</b> _OUT<b>(</b>1<b>)</b><b>,</b> 0<b>,</b> AreaName<b>,</b> <i><font color="#777777">/* See near top of file */</font></i> <b>&</b>area_id<b>)</b><b>;</b> <b>if</b> <b>(</b>e <b>!=</b> NULL<b>)</b> <b>return</b> e<b>;</b> <b>}</b> <i><font color="#777777">/* Try the match */</font></i> e <b>=</b> _swix<b>(</b>CheckURL_Check<b>,</b> _INR<b>(</b>0<b>,</b>2<b>)</b> <b>|</b> _OUTR<b>(</b>0<b>,</b>1<b>)</b><b>,</b> CU_Check_OnEntry_GivenAreaID <b>|</b> CU_Check_OnEntry_GivenURLDescriptor<b>,</b> area_id<b>,</b> d<b>,</b> <b>&</b>match<b>,</b> param<b>)</b><b>;</b> <b>if</b> <b>(</b>e <b>==</b> NULL<b>)</b> <b>{</b> <i><font color="#777777">/* If no match, clear "param" (R1 is preserved on exit for no match) */</font></i> <b>if</b> <b>(</b><b>(</b>match <b>&</b> CU_Check_OnExit_MatchFound<b>)</b> <b>==</b> 0<b>)</b> <b>*</b>param <b>=</b> NULL<b>;</b> <b>}</b> <b>else</b> <b>if</b> <b>(</b>e<b>-></b>errnum <b>==</b> cu_ERROR_AREA_NOT_KNOWN <b>&&</b> allow_fail<b>)</b> <b>{</b> <i><font color="#777777">/* Since allow_fail is true, we area allowed to fail on an area ID */</font></i> <i><font color="#777777">/* lookup. This is because we know IDs can become stale. In this */</font></i> <i><font color="#777777">/* case, try again, but only once. */</font></i> area_id <b>=</b> 0<b>;</b> e <b>=</b> url_match<b>(</b>d<b>,</b> param<b>,</b> false<b>)</b><b>;</b> <b>}</b> <b>return</b> e<b>;</b> <b>}</b></pre> <h2> <a href="#contents" name="history">History</a> </h2> <p /> <table align="center" border="0" cellpadding="0" cellspacing="4" width="95%"> <tr> <td valign="top" style="white-space: nowrap;"><font size="2">Issue A</font></td> <td valign="top" style="white-space: nowrap;"><font size="2">06-Mar-2000</font></td> <td valign="top"> <font size="2"> First draft completed and checked (ADH) </font> </td> </tr> <tr> <td valign="top" style="white-space: nowrap;"><font size="2">Issue B</font></td> <td valign="top" style="white-space: nowrap;"><font size="2">09-Mar-2000</font></td> <td valign="top"> <font size="2"> Released following review (ADH) </font> </td> </tr> <tr> <td valign="top" style="white-space: nowrap;"><font size="2">Issue 1</font></td> <td valign="top" style="white-space: nowrap;"><font size="2">21-Mar-2000</font></td> <td valign="top"> <font size="2"> Corrected a description of R1 that didn't match the description of flags in R0 and corrected description of the way in which fragments are added to existing areas (ADH) </font> </td> </tr> <tr> <td valign="top" style="white-space: nowrap;"><font size="2">Issue 1A</font></td> <td valign="top" style="white-space: nowrap;"><font size="2">22-May-2000</font></td> <td valign="top"> <font size="2"> Extended CheckURL_AddArea to return an area ID in R1. ROM builds have to defer loading of the central configuration file. Gave example code for cacheing an area ID. Few typing errors fixed (ADH) </font> </td> </tr> <tr> <td valign="top" style="white-space: nowrap;"><font size="2">Issue 1B</font></td> <td valign="top" style="white-space: nowrap;"><font size="2">05-Jul-2000</font></td> <td valign="top"> <font size="2"> Corrected example code which wasn't checking on-exit flags of the call to CheckURL_Check (ADH) </font> </td> </tr> <tr> <td valign="top" style="white-space: nowrap;"><font size="2">Issue 2</font></td> <td valign="top" style="white-space: nowrap;"><font size="2">04-Aug-2000</font></td> <td valign="top"> <font size="2"> Released following review (AMR 5390, ADH) </font> </td> </tr> <tr> <td valign="top" style="white-space: nowrap;"><font size="2">Issue 3</font></td> <td valign="top" style="white-space: nowrap;"><font size="2">16-Mar-2001</font></td> <td valign="top"> <font size="2"> Updated automatic section numbering to handle subsectionNumberingSections. Used full subsection numbers for SWIs. Updated references section using links into the drawing office search engine and added validation footer. Overall, all changes were internal. ECO allocated for release (ECO 4428, ADH) </font> </td> </tr> </table> <p /> <h2> <a href="#contents" name="references">References</a> </h2> <p /> The following may prove useful: <p /> <ol type="1"> <li><a name="ref1" href="http://www.faqs.org/rfcs/rfc1630.html">RFC 1630: Uniform Resource Identifiers in WWW</a> ('http://www.faqs.org/rfcs/rfc1630.html' - April 1998).<br /> Official location: <a href="ftp://ftp.isi.edu/in-notes/rfc1630.txt">'ftp://ftp.isi.edu/in-notes/rfc1630.txt'</a> <li><a name="ref2" href="http://www.faqs.org/rfcs/rfc1738.html">RFC 1738: Uniform Resource Locators</a> ('http://www.faqs.org/rfcs/rfc1738.html' - April 1998).<br /> Official location: <a href="ftp://ftp.isi.edu/in-notes/rfc1738.txt">'ftp://ftp.isi.edu/in-notes/rfc1738.txt'</a> <li><a name="ref3" href="http://www.faqs.org/rfcs/rfc1808.html">RFC 1808: Relative Uniform Resource Locators</a> ('http://www.faqs.org/rfcs/rfc1808.html' - April 1998).<br /> Official location: <a href="ftp://ftp.isi.edu/in-notes/rfc1808.txt">'ftp://ftp.isi.edu/in-notes/rfc1808.txt'</a> <li><a name="ref4" href="/wiki/documentation/pages/URL+Fetcher+API+Specification">URL Fetcher API Specification</a> (1215,220/FS issue 3, 12-Nov-1998, ECO 4131) </ol> </notextile>