URI Support

Contents - Index

URI Support

One way GSAK can interface with other applications is via a URI (Uniform Resource Identifier). Many mapping programs allow you to enter a link for your waypoints. This is where you would enter something like http://geocaching.com/whatever. The http:// is the URI that tells your computer to open this link with your default web browser and go to the address provided in that link. Similarly we can now do this with GSAK. That is, we can provide a URI as a link which will perform some "action" in GSAK.

The syntax of the URI is gsak://%FF/action/code/database

Where:

Signature = Literal required so GSAK can determine if the raw data has been HttpDecoded or not. It must always be %FF. (more information)
Action = GSAK action to perform
Code = The waypoint code to perform this action on
Database = (optional) database to select before performing the action. If not given we use the current database.

Currently supported actions are:

FlagSet - Set the user flag for this cache
FlagClear - Clear the user flag for this cache
FlagToggle - Toggle the user flag for this cache
Help - Open the GSAK help file at a selected topic
Macro - Run a GSAK macro
Offline - Show the GSAK generated offline HTML page for the waypoint in your browser
Open - Open a file or URL
Prompt - prompt for selection
Search - Find and position to waypoint in the GSAK database
URL - Call up the URL associated with the waypoint in the GSAK database

Note1: the"open" action is a little different to the other actions. It does not need a code or database. GSAK takes everything after "gsak://open/" verbatim. It then uses this string (it can be a file or URL) to open with the default application associated on your computer. See examples at end for the open action

Note2: the"macro" action has a different syntax to allow for the calling of a macro. Use gsak://%FF/macro/<macro>[?<parameters>][/[<code>][/<database>]]. <macro> is the macro to run. Both "code" and "database" are optional. If you do include "code" then GSAK will position to that code in the database before the macro is run. If you omit the code, but include the database, then that database will be selected before the macro is run (no code moved to). Basically, the syntax above means that any of the following are supported:

1) gsak://%FF/macro/<macro>
2) gsak://%FF/macro/<macro>?<parameters>
3) gsak://%FF/macro/<macro>?<parameters>/<code>
4) gsak://%FF/macro/<macro>?<parameters>/<code>/<database>
5) gsak://%FF/macro/<macro>?<parameters>//<database>
6) gsak://%FF/macro/<macro>/<code>
7) gsak://%FF/macro/<macro>/<code>/<database>
8) gsak://%FF/macro/<macro>//<database>

For more information in passing parameters to a macro see this link.

Note3: the "help" action only needs a topic number, and the syntax is gsak://%FF/Help/nnnnn Where nnnnnn is the help topic number. You can find this topic number via a right click then select "properties" on any topic you open in the help file. For example if you wanted to display the main macro help topic use: gsak://%FF/help/21000 This should come in handy when you want to display a GSAK help topic from an applications other than GSAK (external text editor for example).

Note4: The default behaviour when you use GSAK URI support is to make GSAK the active application, then run the action. There are times when you may want to stay in the application that has the URI link. All actions support the addition of ":silent" to them. When you click on a URI link that uses ":silent" you should remain in that application, but GSAK will "flash" in the task bar to let you know that something is happening with it.To silently toggle the user flag: gsak://%FF/flagtoggle:silent/%code/%database

For example, if you wanted a hotlink in Memory map that brings up the GSAK generated offline HTML for code "GC141E" and this cache is in your database "Default":

gsak://%FF/offline/GC141E/Default

By using Special tags when you do an export to your favourite mapping program, you can automatically have each link perform the required action. Following on from a Memory Map example, if you wanted all your waypoints in Memory Map to have each link resolve to showing the GSAK offline HTML page you would enter the following in the "File Link" box:
gsak://%FF/offline/%code/%database

You could also get quite creative with this, as HTML supports this type of linking. For example it would then be possible to write HTML code that invokes GSAK from a link in your browser:

<a href="gsak://%FF/search/GC141E/Default">Search GSAK </a>

Even easier, would be to set up custom URLs (Tools=>Options=>HTML) that would allow you to "action" GSAK from any GSAK generated HTML page. For example, if you wanted to be able to manipulate the Userflags from GSAK HTML, add the following custom URLs (notice that you must precede each by ! - exclamation mark)

!Flag Toggle=gsak://%FF/flagtoggle/%code/%database
!Flag Set=gsak://%FF/flagset/%code/%database
!Flag Clear=gsak://%FF/flagclear/%code/%database

Now from any generated GSAK HTML page you can click on the links as required:

Open action examples:

To open a text file in your default text editor:

"gsak://%FF/open/c:\temp\test.txt"

To force GSAK to display a particular online URL:

"gsak://%FF/open/http://gsak.net"

To force GSAK to display a html file in your default browser

"gsak://%FF/open/c:\temp\offline.html"