BeginDeserialization()
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.
Result
The ALPOT_ type of the first object, or ALPOT_None.
DictGetOptionForKey()
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.
DictSetObjectForKey()
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.
FindApplicationA()
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.
GetAppLibAttrsA()
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.
GetApplicationAttrsA()
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.
LockApplicationIcon()
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.
NotifyA()
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.
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.
PrefsArrayA()
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.
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.
PrefsBaseObjectA()
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.
Result
obj, or the object an Alloc or ALPO_Copy method made; NULL after
ALPO_Release freed it.
PrefsBinaryA()
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.
Result
obj, or the object an Alloc or ALPO_Copy method made; NULL after
ALPO_Release freed it.
PrefsDateA()
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.
Result
obj, or the object an Alloc or ALPO_Copy method made; NULL after
ALPO_Release freed it.
PrefsDictionaryA()
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.
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.
PrefsNumberA()
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.
Result
obj, or the object an Alloc or ALPO_Copy method made; NULL after
ALPO_Release freed it.
PrefsStringA()
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.
Result
obj, or the object an Alloc or ALPO_Copy method made; NULL after
ALPO_Release freed it.
ReadPrefsA()
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.
Result
0, or ALPOEF_ flags. dict is left empty on failure.
RegisterApplicationA()
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.
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.
SendApplicationMsg()
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.
SetAppLibAttrsA()
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.
Result
FALSE if a tag could not be set.
SetApplicationAttrsA()
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.
UnregisterApplicationA()
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().
Result
FALSE if there was no such application, or its icon is locked and
UNREGAPP_WaitForUnlock is FALSE.
WritePrefsA()
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.
Result
0, or ALPOEF_ flags.