Synopsis

ULONG BeginDeserialization(
         struct ALPOGetProcInfo * info );

Function

Read a stream up to its first object's open tag, for reading
PrefsObjects XML by hand: allocate an object of the type returned
and ALPO_Deserialize it with the same info.

Inputs

info - getChProc, unGetChProc, encoding, and key_otag pointing to
       TAGBUFFER_SIZE bytes.

Result

The ALPOT_ type of the first object, or ALPOT_None.

Synopsis

BOOL DictGetBoolForKey(
         PrefsObject * dict,
         CONST_STRPTR key,
         BOOL defBool );

Function

The number stored for a key as a BOOL, or defBool if dict is NULL
or holds no number for key.

Synopsis

LONG DictGetIntegerForKey(
         PrefsObject * dict,
         CONST_STRPTR key,
         LONG defInt );

Function

The number stored for a key as a LONG, or defInt if dict is NULL
or holds no number for key.

Synopsis

PrefsObject * DictGetObjectForKey(
         PrefsObject * dict,
         CONST_STRPTR key );

Function

The object stored in a dictionary for a key, or NULL. The
dictionary keeps owning it.

Synopsis

LONG DictGetOptionForKey(
         PrefsObject * dict,
         CONST_STRPTR key,
         CONST_STRPTR * optionsTable,
         LONG defaultOption );

Function

Look the string stored for key up in a NULL-terminated table,
ignoring case.

Result

Its index in the table, or defaultOption if dict, the table or the
string is missing or the string is not in the table.

Synopsis

CONST_STRPTR DictGetStringForKey(
         PrefsObject * dict,
         CONST_STRPTR key,
         CONST_STRPTR defStr );

Function

The string stored for a key, or defStr if dict is NULL or holds no
string for key. The string belongs to the dictionary.

Synopsis

BOOL DictSetObjectForKey(
         PrefsObject * dict,
         PrefsObject * obj,
         CONST_STRPTR key );

Function

Store obj in the dictionary for key, releasing what was stored for
key before. The dictionary takes over the caller's reference.

Result

FALSE if dict, obj or key is NULL or memory ran out; obj then
still belongs to the caller.

Notes

Storing the object already held for key drops one reference only if
the object has more than one, since a borrowed pointer and a retained
one cannot be told apart: an object also held elsewhere must be
retained before it is stored over itself.

Synopsis

ULONG FindApplicationA(
         struct TagItem * tags );

ULONG FindApplication(
         TAG tag, ... );

Function

Find a registered application by FINDAPP_Name (the first instance),
FINDAPP_AppIdentifier (one instance) or FINDAPP_FileName.

Result

The application ID, or 0.

Synopsis

VOID FreeApplicationList(
         struct MinList * list );

Function

Free a list from GetApplicationList().

Synopsis

BOOL GetAppLibAttrsA(
         struct TagItem * tags );

BOOL GetAppLibAttrs(
         TAG tag, ... );

Function

Read library-wide attributes, APPLIBATTR_ tags marked (G).
The arrays are copies: ALPO_Release them when done. Their entries
are dictionaries with the LUA_ or LUD_ keys, most recent first.

Result

FALSE if a tag could not be read.

Synopsis

BOOL GetApplicationAttrsA(
         ULONG appID,
         struct TagItem * tags );

BOOL GetApplicationAttrs(
         ULONG appID,
         TAG tag, ... );

Function

Read attributes of an application. ti_Data points to the storage:
an APTR or STRPTR for pointer attributes, a ULONG for the others.
Strings stay valid while the application is registered.

APPATTR_MainPrefsDict is the application's own dictionary, made
empty if it had none; APPATTR_LastUsedDocsArray is a copy, to be
ALPO_Release'd. APPATTR_IconType may only be used while the icon
is locked with LockApplicationIcon().

Result

FALSE if there was no such application or a tag is unknown.

Synopsis

struct MinList * GetApplicationList();

Function

A snapshot of the registered applications, as a list of
struct ApplicationNode. Free it with FreeApplicationList().

Synopsis

BOOL LockApplicationIcon(
         ULONG appID );

Function

Lock an application's icon so that APPATTR_IconType can be read and
the icon or docky used. While it is locked the application cannot
change its icon type, and UnregisterApplication() waits for up to
five seconds; after that the application is gone but its icon
information stays valid until the last unlock. Locks nest.

A dock must unlock the icon as soon as it is sent
APPLIBMT_AppWantsChangeIconType or APPLIBMT_AppUnregister.

Result

FALSE if there is no such application or it is unregistering.

See also

UnlockApplicationIcon()

Synopsis

ULONG NotifyA(
         ULONG appID,
         struct TagItem * tags );

ULONG Notify(
         ULONG appID,
         TAG tag, ... );

Function

Show a pop-up notification for a registered application, and add it
to the notification log. It closes by itself after a few seconds
(a priority 10 one stays until closed) and asks nothing of the user.

Double-clicking it sends APPNOTIFY_BackMsg to the application as an
APPLIBMT_CustomMsg; a BackMsg starting with "URL:" opens the URL in
the default browser instead.

The notification server, SYS:System/Notifications, is started if
it is not running. How pop-ups look and which applications may show
them is set in the Notifications preferences.

Inputs

appID - the application ID from RegisterApplication().
tags  - APPNOTIFY_ tags; at least a title or a text, unless
        APPNOTIFY_Withdraw takes back earlier pop-ups.

Result

APPNOTIFY_OK_MSGQUEUED (0), or an APPNOTIFY_ERROR_ code:
_APPNOTREGISTERED, _TAGS, _GAMEMODEACTIVE (nothing is shown while
an application is in game mode), _APPNOTALLOWED (switched off in
the preferences), _TOOMANYMESSAGESQUEUED, _SERVERNOTRUNNING or
_OUTOFMEM.

Notes

Use notifications sparingly, keep them short, and never use one for
an error or a question: the user may never see it.

Synopsis

PrefsObject * PrefsArrayA(
         PrefsObject * obj,
         ULONG * error,
         struct TagItem * tags );

PrefsObject * PrefsArray(
         PrefsObject * obj,
         ULONG * error,
         TAG tag, ... );

Function

Run methods on an array, objects by index: ALPO_ and ALPOARR_
methods.

Inputs

obj   - the object, or NULL for the ALPO_Alloc methods.
error - NULL, or where to store the ALPOEF_ flags of the methods
        that failed; 0 if all succeeded.
tags  - the methods, run in order. Methods without a parameter
        take 0.

Result

obj, or the object an Alloc or ALPO_Copy method made; NULL after
ALPO_Release freed it.

Notes

The Add, Insert and Replace methods take over the caller's
reference.
Storing the object already held at the index drops one reference only if
the object has more than one, since a borrowed pointer and a retained
one cannot be told apart: an object also held elsewhere must be
retained before it is stored over itself.

See also

libraries/application.h

Synopsis

PrefsObject * PrefsBaseObjectA(
         PrefsObject * obj,
         ULONG * error,
         struct TagItem * tags );

PrefsObject * PrefsBaseObject(
         PrefsObject * obj,
         ULONG * error,
         TAG tag, ... );

Function

Run methods on any PrefsObject. Only the ALPO_ methods common to all
types apply; it cannot allocate.

Inputs

obj   - the object, or NULL for the ALPO_Alloc methods.
error - NULL, or where to store the ALPOEF_ flags of the methods
        that failed; 0 if all succeeded.
tags  - the methods, run in order. Methods without a parameter
        take 0.

Result

obj, or the object an Alloc or ALPO_Copy method made; NULL after
ALPO_Release freed it.

See also

libraries/application.h

Synopsis

PrefsObject * PrefsBinaryA(
         PrefsObject * obj,
         ULONG * error,
         struct TagItem * tags );

PrefsObject * PrefsBinary(
         PrefsObject * obj,
         ULONG * error,
         TAG tag, ... );

Function

Run methods on binary data: ALPO_ and ALPOBIN_ methods. Prefer the
other types, which can be extended later.

Inputs

obj   - the object, or NULL for the ALPO_Alloc methods.
error - NULL, or where to store the ALPOEF_ flags of the methods
        that failed; 0 if all succeeded.
tags  - the methods, run in order. Methods without a parameter
        take 0.

Result

obj, or the object an Alloc or ALPO_Copy method made; NULL after
ALPO_Release freed it.

See also

libraries/application.h

Synopsis

PrefsObject * PrefsDateA(
         PrefsObject * obj,
         ULONG * error,
         struct TagItem * tags );

PrefsObject * PrefsDate(
         PrefsObject * obj,
         ULONG * error,
         TAG tag, ... );

Function

Run methods on a date: ALPO_ and ALPODAT_ methods.

Inputs

obj   - the object, or NULL for the ALPO_Alloc methods.
error - NULL, or where to store the ALPOEF_ flags of the methods
        that failed; 0 if all succeeded.
tags  - the methods, run in order. Methods without a parameter
        take 0.

Result

obj, or the object an Alloc or ALPO_Copy method made; NULL after
ALPO_Release freed it.

See also

libraries/application.h

Synopsis

PrefsObject * PrefsDictionaryA(
         PrefsObject * obj,
         ULONG * error,
         struct TagItem * tags );

PrefsObject * PrefsDictionary(
         PrefsObject * obj,
         ULONG * error,
         TAG tag, ... );

Function

Run methods on a dictionary, objects by key: ALPO_ and ALPODICT_
methods.

Inputs

obj   - the object, or NULL for the ALPO_Alloc methods.
error - NULL, or where to store the ALPOEF_ flags of the methods
        that failed; 0 if all succeeded.
tags  - the methods, run in order. Methods without a parameter
        take 0.

Result

obj, or the object an Alloc or ALPO_Copy method made; NULL after
ALPO_Release freed it.

Notes

The Set, Insert and Replace methods take over the caller's
reference.
Storing the object already held for key drops one reference only if
the object has more than one, since a borrowed pointer and a retained
one cannot be told apart: an object also held elsewhere must be
retained before it is stored over itself.

See also

libraries/application.h

Synopsis

PrefsObject * PrefsNumberA(
         PrefsObject * obj,
         ULONG * error,
         struct TagItem * tags );

PrefsObject * PrefsNumber(
         PrefsObject * obj,
         ULONG * error,
         TAG tag, ... );

Function

Run methods on a number (LONG, BOOL or double): ALPO_ and ALPONUM_
methods.

Inputs

obj   - the object, or NULL for the ALPO_Alloc methods.
error - NULL, or where to store the ALPOEF_ flags of the methods
        that failed; 0 if all succeeded.
tags  - the methods, run in order. Methods without a parameter
        take 0.

Result

obj, or the object an Alloc or ALPO_Copy method made; NULL after
ALPO_Release freed it.

See also

libraries/application.h

Synopsis

PrefsObject * PrefsStringA(
         PrefsObject * obj,
         ULONG * error,
         struct TagItem * tags );

PrefsObject * PrefsString(
         PrefsObject * obj,
         ULONG * error,
         TAG tag, ... );

Function

Run methods on a string: ALPO_ and ALPOSTR_ methods.

Inputs

obj   - the object, or NULL for the ALPO_Alloc methods.
error - NULL, or where to store the ALPOEF_ flags of the methods
        that failed; 0 if all succeeded.
tags  - the methods, run in order. Methods without a parameter
        take 0.

Result

obj, or the object an Alloc or ALPO_Copy method made; NULL after
ALPO_Release freed it.

See also

libraries/application.h

Synopsis

ULONG ReadPrefsA(
         PrefsObject * dict,
         struct TagItem * tags );

ULONG ReadPrefs(
         PrefsObject * dict,
         TAG tag, ... );

Function

Empty a dictionary and fill it from a prefs file or a stream.

Inputs

dict - the dictionary.
tags - READPREFS_AppID (that application's prefs file),
       READPREFS_FileName (a name below ENV:, or a full path) or
       READPREFS_GetProcInfo (a stream). A file is read from ENV:,
       or from ENVARC: if that fails; READPREFS_ReadENV and
       READPREFS_ReadENVARC switch either off.

Result

0, or ALPOEF_ flags. dict is left empty on failure.

Synopsis

ULONG RegisterApplicationA(
         CONST_STRPTR name,
         struct TagItem * tags );

ULONG RegisterApplication(
         CONST_STRPTR name,
         TAG tag, ... );

Function

Register the calling program as an application. It gets an ID, a
unique identifier ("name.urlidentifier", with "_1", "_2" ... added
for further instances) and a message port, see APPATTR_Port.

Inputs

name - application name, without spaces.
tags - REGAPP_ tags. With REGAPP_LoadPrefs the application's prefs
       file, ENV:[ENVDir/]name.urlidentifier.xml (or ENVARC: if
       that is missing), is read into APPATTR_MainPrefsDict.

Result

The application ID, or 0. With REGAPP_UniqueApplication, 0 is also
returned when the application is already running; that instance is
sent an APPLIBMT_Unique message.

Notes

Call UnregisterApplication() from the same task before exiting.

See also

UnregisterApplicationA() GetApplicationAttrsA()

Synopsis

BOOL SendApplicationMsg(
         ULONG senderAppID,
         ULONG receiverAppID,
         struct ApplicationMsg * msg,
         ULONG type );

Function

Send a message to an application, or with receiverAppID 0 to every
application except the sender. The library sends a copy: msg, and
the string of an APPLIBMT_CustomMsg, APPLIBMT_OpenDoc or
APPLIBMT_PrintDoc, can be reused at once. msg may be NULL for the
other types.

The APPLIBMT_App... types always go to every application with
AppNotifications set, the APPLIBMT_Blanker... types to every one
with BlankerNotifications set, whatever receiverAppID is.

Result

TRUE if at least one application was sent the message.

Synopsis

BOOL SetAppLibAttrsA(
         ULONG dummy,
         struct TagItem * tags );

BOOL SetAppLibAttrs(
         ULONG dummy,
         TAG tag, ... );

Function

Change library-wide attributes, APPLIBATTR_ tags marked (S). The
settings are saved at once to ENV:Sys/application.xml and
ENVARC:Sys/application.xml.

Inputs

dummy - 0.

Result

FALSE if a tag could not be set.

Synopsis

BOOL SetApplicationAttrsA(
         ULONG appID,
         struct TagItem * tags );

BOOL SetApplicationAttrs(
         ULONG appID,
         TAG tag, ... );

Function

Change the attributes of an application, see the APPATTR_ tags
marked (S) in <libraries/application.h>.

APPATTR_IconType fails while a dock has the icon locked; the docks
are asked to unlock it, so try again a little later.
APPATTR_MainPrefsDict hands the dictionary to the application,
which releases the one it had. APPATTR_FlushPrefs TRUE writes the
dictionary to ENV: and ENVARC: now, whether or not the application
registered with REGAPP_SavePrefs.

Result

FALSE if there was no such application or a tag could not be set.

Synopsis

VOID UnlockApplicationIcon(
         ULONG appID );

Function

Undo one LockApplicationIcon().

Synopsis

BOOL UnregisterApplicationA(
         ULONG appID,
         struct TagItem * tags );

BOOL UnregisterApplication(
         ULONG appID,
         TAG tag, ... );

Function

Remove an application registered with RegisterApplication().
Messages still waiting on its port are replied, game mode and a
blanker veto are undone, and with REGAPP_SavePrefs the prefs are
written to ENV: and ENVARC:.

Docks that locked the application's icon are sent
APPLIBMT_AppUnregister; until they unlock it, or for at most five
seconds, the application stays. After that it is gone, but the
icon information a dock read stays valid until its last
UnlockApplicationIcon().

Inputs

appID - the application ID.
tags  - UNREGAPP_WaitForUnlock: FALSE to fail at once while the
        icon is locked, instead of waiting. NULL is fine.

Result

FALSE if there was no such application, or its icon is locked and
UNREGAPP_WaitForUnlock is FALSE.

Synopsis

ULONG WritePrefsA(
         PrefsObject * dict,
         struct TagItem * tags );

ULONG WritePrefs(
         PrefsObject * dict,
         TAG tag, ... );

Function

Write a dictionary to a prefs file or a stream.

Inputs

dict - the dictionary.
tags - WRITEPREFS_AppID, WRITEPREFS_FileName or
       WRITEPREFS_PutProcInfo, as for ReadPrefsA(). A file is
       written to ENV: (WRITEPREFS_WriteENV, default TRUE) and to
       ENVARC: (WRITEPREFS_WriteENVARC, default FALSE).

Result

0, or ALPOEF_ flags.