external/openurl/developer/Autodocs/openurl.doc

   1 TABLE OF CONTENTS
   2
   3 openurl.library/--background--
   4 openurl.library/--rexxhost--
   5 openurl.library/URL_FreePrefsA
   6 openurl.library/URL_GetPrefsA
   7 openurl.library/URL_LaunchPrefsAppA
   8 openurl.library/URL_OpenA
   9 openurl.library/URL_SetPrefsA
  10
  11 \fopenurl.library/--background--
  12
  13     PURPOSE
  14
  15       The openurl.library provides a means whereby developers can
  16       easily add "send URL to browser" functionality their
  17       applications.
  18
  19       Users may configure their preferred browser(s) through the
  20       preference program.
  21
  22       To utilise the library, you only need the URL_Open() call.
  23       All other function calls are only useful if you're making
  24       a preferences program.
  25
  26       If you want to program your own preferences program, read
  27       this documentation and study the included source to the MUI
  28       preference program. If you have any questions, contact us
  29       via our website on SourceForge.net at
  30       http://sourceforge.net/projects/openurllib.
  31
  32       OpenURL was originally developped, up to version 3.0, by
  33       Troels Walsted Hansen of Ultima Thule Software.
  34       Troels put OpenURL in the public domain.
  35
  36       From version 3.1 to 7.1, OpenURL was developed by:
  37       - Alfonso Ranieri <alforan@tin.it>
  38       - Stefan Kost <ensonic@sonicpulse.de>
  39
  40       Since version 7.2, OpenURL has been made open source and
  41       is developped by the OpenURL Team.
  42
  43 \fopenurl.library/--rexxhost--
  44
  45     HOST INTERFACE
  46
  47     openurl.library provides an ARexx function host interface
  48     that enables ARexx programs to use it. The functions provided
  49     by the interface are directly related to the functions
  50     described herein, with the differences mostly being in the
  51     way they are called.
  52
  53     The function host library vector is located at offset -66
  54     from the library. This is the value you provide to ARexx in
  55     the AddLib() function call. Note that this is different from
  56     the usual -30 offset of other libraries! Also, be sure to ask
  57     for version 3 of the library when you AddLib() it. See below
  58     for an example of how to use it properly.
  59
  60     FUNCTIONS
  61       success = OPENURLPREFS()
  62
  63       success = OPENURL(URL/A,SHOW/S,NOSHOW/S,TOFRONT/S,NOTOFRONT/S,NEWWIN/S,
  64                         NONEWWIN/S,LAUNCH/S,NOLAUNCH/S)
  65
  66     EXAMPLE
  67       /* OpenURL.rexx */
  68       PARSE ARG url
  69       OPTIONS RESULTS
  70
  71       /* Load the openurl.library as a function host */
  72       IF ~SHOW('L','openurl.library') THEN
  73         CALL ADDLIB('openurl.library',3,-66)
  74
  75       IF url="" THEN DO
  76         SAY "Usage:"
  77         SAY "  rx OpenURL <url>"
  78         EXIT
  79       END
  80
  81       SAY "Opening URL in new browser window..."
  82       success = OpenURL(url, SHOW, TOFRONT, NEWWIN, LAUNCH)
  83
  84       IF success=0 THEN
  85         SAY "Failed to open URL"
  86       ELSE
  87         SAY "Succeeded in opening URL"
  88
  89       SAY "Launching OpenURL prefs program..."
  90       success = OpenURLPrefs()
  91
  92       IF success=0 THEN
  93         SAY "Failed to launch OpenURL prefs program"
  94       ELSE
  95         SAY "Succeeded in launching OpenURL prefs program"
  96
  97       EXIT
  98
  99 \fopenurl.library/URL_FreePrefsA
 100
 101     NAME
 102       URL_FreePrefsA - Free a copy of openurl.library preferences. (V1)
 103
 104     SYNOPSIS
 105       URL_FreePrefsA(prefs,attrs)
 106                      a0    a1
 107
 108       void URL_FreePrefsA(struct URL_Prefs *,struct TagItem *);
 109
 110       URL_FreePrefsA(prefs,tag,...)
 111                      a0    a1
 112
 113       void URL_FreePrefs(struct URL_Prefs *,Tag,...);
 114
 115     FUNCTION
 116       Free a copy of openurl.library preferences. Call this when
 117       you're done with the prefs that URL_GetPrefsA() gave you.
 118       Currently no attribute is defined.
 119
 120     INPUTS
 121       prefs - pointer to URL_Prefs structure
 122       attrs - attributes list
 123
 124     SEE ALSO
 125       URL_GetPrefsA()
 126
 127 \fopenurl.library/URL_GetPrefsA
 128
 129     NAME
 130       URL_GetPrefsA - Get a copy of openurl.library preferences.
 131
 132     SYNOPSIS
 133       prefs = URL_GetPrefsA(attrs)
 134       d0                    a0
 135
 136       struct URL_Prefs *URL_GetPrefsA(struct TagItem *);
 137
 138       prefs = URL_GetPrefsA(tag1,...)
 139       d0                    a0
 140
 141       struct URL_Prefs *URL_GetPrefs(Tag,...);
 142
 143     FUNCTION
 144       Get a copy of openurl.library preferences. Call this to get
 145       your own copy of the preferences to read from. When you're
 146       done you have to use URL_FreePrefs() to free it.
 147
 148       The attributes defined are:
 149
 150       - URL_GetPrefs_Mode (ULONG)
 151         One of:
 152
 153         - URL_GetPrefs_Mode_Default
 154           You get gefault values
 155
 156         - URL_GetPrefs_Mode_LastSaveds
 157           You get what in ENVARC:OpenURL.prefs
 158
 159         - URL_GetPrefs_Mode_Restore
 160           You get what in ENV:OpenURL.prefs
 161
 162       - URL_GetPrefs_FallBack (BOOL)
 163         If TRUE, the functions fails iff no mem
 164         If FALSE, the functions may fail if the
 165         prefs are not found.
 166
 167     INPUTS
 168       tags - attributes
 169
 170     RESULT
 171       Returns a valid pointer to a URL_Prefs structure, or NULL
 172       for failure.
 173
 174     NOTES
 175       Remember to check the version number of the structure you
 176       get in return! Do not make any assumptions about the
 177       structure if it doesn't match the version that you handle.
 178
 179     SEE ALSO
 180       URL_FreePrefsA() URL_SetPrefsA()
 181
 182 \fopenurl.library/URL_LaunchPrefsAppA
 183
 184     NAME
 185       URL_LaunchPrefsAppA - Launch openurl.library prefs program (V3)
 186
 187     SYNOPSIS
 188       success = URL_LaunchPrefsAppA(attrs)
 189       d0                            a1
 190
 191       ULONG URL_LaunchPrefsAppA(struct TagItem *)
 192
 193       success = URL_LaunchPrefsApp(tag1,...)
 194       d0                           a1
 195
 196       ULONG URL_LaunchPrefsApp(Tag,...)
 197
 198     FUNCTION
 199       Use this function if you want to offer a way to configure
 200       openurl.library from inside your application. Currently no
 201       attribute is defined.
 202
 203     INPUTS
 204       attrs - attributes list
 205
 206     RESULT
 207       TRUE for success, FALSE for error.
 208
 209 \fopenurl.library/URL_GetAttr
 210
 211     NAME
 212       URL_GetAttr - Obtains one OpenURL attribute
 213
 214     SYNOPSIS
 215       res = URL_GetAttr(attr,storage)
 216       d0                d0   a0
 217
 218       ULONG URL_GetAttr(ULONG,ULONG *)
 219
 220     FUNCTION
 221       Obtains one OpenURL attribute.
 222
 223       attr is one of:
 224
 225       - URL_GetAttr_Version (ULONG)
 226         openurl.library version
 227
 228       - URL_GetAttr_Revision (ULONG)
 229         openurl.library revision
 230
 231       - URL_GetAttr_VerString (STRPTR)
 232         openurl.library version string,
 233         e.g. "openurl.library 5.0 (20.3.2003)"
 234
 235       - URL_GetAttr_PrefsVer (ULONG)
 236         openurl.library preferences version
 237
 238     INPUTS
 239       attr - the attribute to read
 240       storage - where to store the value of attr
 241
 242     RESULT
 243       TRUE if the attribute may be obtained, FALSE otherwise.
 244
 245 \fopenurl.library/URL_OpenA
 246
 247     NAME
 248       URL_OpenA - Open an URL by sending it to a browser.      (V1)
 249
 250     SYNOPSIS
 251       success = URL_OpenA(url, tags)
 252       d0                  a0   a1
 253
 254       ULONG URL_OpenA(STRPTR, struct TagItem *);
 255
 256       success = URL_Open(url, firsttag, ...)
 257
 258     FUNCTION
 259       Open URL, optionally uniconify browser, bringing its screen
 260       to front, opening the URL in a new browser window and
 261       launching the browser if it isn't running.
 262
 263     INPUTS
 264       url - The URL.
 265       tags - see below for allowed ones.
 266
 267     TAGS
 268       The defaults shown next to each tag is the "default
 269       default", users may configure their own defaults starting
 270       with V2.
 271
 272       - URL_Show (BOOL)
 273         show/uniconify browser, default TRUE.
 274
 275       - URL_BringToFront (BOOL)
 276         bring browser to front, default TRUE.
 277
 278       - URL_NewWindow (BOOL)
 279         open URL in new window, default FALSE.
 280
 281       - URL_Launch (BOOL)
 282         launch browser when not running, default TRUE.
 283
 284     RESULT
 285      Returns TRUE for success, and FALSE for failure to
 286      contact/start any browser.
 287
 288     NOTES
 289      From V2, the ARexx commands used to display URLs are sent
 290      asynchronously, in other words, the functions returns
 291      immediatedly, even if the browser is slow in replying the
 292      ARexx message, or possibly crashed and not replying at all.
 293
 294     EXAMPLE
 295      See the included OpenURL.c.
 296
 297 \fopenurl.library/URL_SetPrefsA
 298
 299     NAME
 300       URL_SetPrefsA - Set openurl.library preferences.            (V1)
 301
 302     SYNOPSIS
 303       success = URL_PrefsA(prefs,attrs)
 304       d0                   a0    a0
 305
 306       ULONG URL_SetPrefs(struct URL_Prefs *,struct TagItem *);
 307
 308       success = URL_SetPrefsA(prefs,Tag1,...)
 309       d0                      a0    a0
 310
 311       ULONG URL_SetPrefs(struct URL_Prefs *,Tag,...);
 312
 313     FUNCTION
 314       Set openurl.library preferences. Call this when the user
 315       has finished editing the preferences and pressed Save or
 316       Use in your preference program.
 317
 318       The attributes defined are:
 319
 320       - URL_SetPrefs_Save (BOOL)
 321         If TRUE, preferences are saved to ENVARC: and ENV:
 322         If FALSE, preferences are saved only to ENV:
 323         Default FALSE
 324
 325     INPUTS
 326       prefs - pointer to URL_Prefs structure
 327       attrs - attributes
 328
 329     RESULT
 330       TRUE for success, FALSE for error.
 331
 332     NOTES
 333       The whole structure, including linked list is copied, so you
 334       must free your own copy.
 335
 336     SEE ALSO
 337       URL_GetPrefsA()
 338 \f