BOOL AddNamedObject( struct NamedObject * nameSpace, struct NamedObject * object );
Adds a given NamedObject to a NameSpace which is addressed through a second NamedObject. Allows you to link a common group of NamedObjects together. If the NameSpace doesn't support duplicate names, then a search for a duplicate will be made, and FALSE returned if one is found.
nameSpace - The NameSpace to add the NamedObject object to. If this value is NULL, then the NamedObject will be added to the root NameSpace. This is useful for sharing NamedObjects between Tasks. object - The NamedObject to add to the NameSpace.
If the NamedObject can be added to either the supplied NameSpace or the system global NameSpace, this function will return TRUE. Otherwise it will return FALSE. This will generally happen when the NSF_NODUPS flag is set and this NamedObject has the same name as a second object, or when the object is already in a NameSpace.
See BUGS.
Although the AmigaOS 3.1 autodocs did not say so, under 3.0 you couldn't add a NamedObject to a NameSpace when the NamedObject you were adding had a NameSpace itself. This has changed. This is because the autodocs did not say this, and they are right :)
struct TagItem * AllocateTagItems( ULONG numTags );
Allocate a number of TagItems in an array for whatever you like. The memory allocated will be cleared.
numTags - The number of TagItems to allocate.
A pointer to an array of struct TagItem containing numTags tags.
struct TagItem *tagList; tagList = AllocateTagItems( 4 ); tagList[0].ti_Tag = NA_Name; tagList[0].ti_Data = (IPTR)"A list of tags"; tagList[3].ti_Tag = TAG_DONE; \* Do what you want with your TagList here ... *\ FreeTagItems( tagList );
The number you supply must include the terminating tag (ie TAG_DONE) There is no provision for extra TagItems at the end of the list. If the number of tags to allocate is zero, then none will be.
struct NamedObject * AllocNamedObjectA( CONST_STRPTR name, CONST struct TagItem * tagList ); struct NamedObject * AllocNamedObject( CONST_STRPTR name, TAG tag, ... );
Allocates a new NamedObject and initializes it as requested. This object can then be used as an object in a name space. Optionally you give this object a name space, and use it to nest name spaces. You can also allocate some memory which is attached to this object for your own personal use. When the object is allocated, it will automatically have one user. To allow other users to remove this object from a namespace, you must call ReleaseNamedObject() on this object.
name - The name of the NamedObject. Obviously this MUST be specified (otherwise it wouldn't be named would it?) tagList - A TagList containing some extra information for this NamedObject. These are: ANO_NameSpace: Allocate a NameSpace for this NamedObject. This will allow you to link other NamedObjects into a group. You cannot add a NamedObject with a NameSpace to another NameSpace. Boolean, default is FALSE. ANO_UserSpace: This tag says that you want extra memory allocated for a UserSpace. The ti_Data field of this TagItem contains the amount of memory to allocate. Specifying this Tag with a ti_Data of 0, is equivalent to the default, which is no UserSpace. The UserSpace address can be found in the no_Object field of the NamedObject structure. ANO_Priority: This is the List priority of the NamedObject and should be a signed BYTE value between -128 and 127. This is taken into account in adding and finding NamedObjects, as the highest priority NamedObject will be returned first. The default value is 0. ANO_Flags: This allows you to initialize the value of the NameSpace flags which control certain aspects of the NameSpace. See the file utility/name.h.
A pointer to a new NamedObject, or NULL if the allocation failed due to no free memory.
void Amiga2Date( ULONG seconds, struct ClockData * result );
Convert the time value given as the number of seconds since the 1st of January 1978 (00:00:00 1.1.78), to a more useful values, which is easier for most people to understand. These values will be stored in the ClockData structure whose address is passed as an argument.
seconds - Number of seconds since 1.1.78 00:00:00 result - The ClockData structure to store the information in.
The ClockData structure will contain the converted time values.
void ApplyTagChanges( struct TagItem * list, struct TagItem * changelist ); void ApplyTagChangesTags( struct TagItem * list, TAG tag, ... );
LONG AttemptRemNamedObject( struct NamedObject * object );
Checks to see whether a NamedObject can be removed. If the object is in use, or in the process of being removed, this function will return a failure code. If the object can be removed, this function will remove it and the object will be available for freeing. You must have previously have called FindNamedObject() on this object.
object - NamedObject to attempt to remove. The address of the NameSpace is contained within the NamedObject.
If the NamedObject can be removed, then it will be removed from the list. Otherwise the routine will just return. If the NamedObject has a removal message associated with it that message will be returned to the owner of the NamedObject.
IPTR CallHookPkt( struct Hook * hook, APTR object, APTR paramPacket );
Call the callback hook defined by a Hook structure. This is effectively a long jump to the hook->h_Entry vector of the structure. The Hook will be called with the same arguments as this function. If your compiler cannot support correctly registered arguments (most can), you can use the HookEntry function defined in amiga.lib to push the arguments on the stack and call your function. See the include file utility/hooks.h for more information.
hook - Pointer to an initialized Hook structure. See the include file <utility/hooks.h> for a definition. object - The object that this Hook is to act upon. paramPacket - The arguments to this callback. This will depend entirely on the type of the object.
Depends upon the Hook itself.
If your callback function does not have the correct register definitions, the result of this function is entirely unreliable. You can get the correct register definitions by using the AROS_UFHA() macros (See <utility/hooks.h>).
amiga.lib/CallHook()
ULONG CheckDate( struct ClockData * date );
Examine the date described in the ClockData structure and determine whether it is a valid date. In particular this checks whether the ranges of the fields are within normal limits. This function does not check whether the wday field of the ClockData structure is valid.
date - A ClockData structure desribing the date to check.
If the date is valid, the number of seconds from midnight 1-Jan-1978 AD to the date, or 0 if the date is invalud.
The date 01-Jan-78 00:00:00 is actually returned as invalid. This also assumes that the ClockDate refers to a date in the Gregorian calendar. (60 sec/min, 60 min/hour, 24 hr/day, 12 months/year).
Does not check whether the 29/2 is valid outside of a leap year.
struct TagItem * CloneTagItems( struct TagItem * tagList ); struct TagItem * CloneTagItemsTags( TAG tag, ... );
Duplicates a TagList. The input TagList can be NULL, in which case an empty TagList will be returned.
tagList - The TagList that you want to clone
A TagList which contains a copy of the TagItems contained in the original list. The list is cloned so that calling FindTagItem() on a tag in the clone will return the same value as that in the original list (assuming the original has not been modified).
struct TagItem *tagList, *tagListClone; \* Set up the original taglist tagList *\ tagListClone = CloneTagItems( tagList ); \* Do what you want with your TagList here *\ FreeTagItems( tagListClone );
ULONG Date2Amiga( struct ClockData * date );
Converts the information given in the struct ClockData *date, into the number of seconds that have past since the 1st of January 1978.
date - Contains the information about the time.
The number of seconds since 1.1.1978
void FilterTagChanges( struct TagItem * changeList, const struct TagItem * originalList, BOOL apply );
This function will scan through changeList, and if an item in changeList exists in originalList, but both items data values are equal, then the item in changeList will be removed from the list. If the value of apply is TRUE, then if the datas are different then the values in originalList will be updated to match those in changeList.
changeList - List of new tags (may be NULL). originalList - List of existing tags (may be NULL). apply - Boolean flag as to whether the values in originalList should be updated to match those in changeList.
The changeList will be modified to show altered items, and if requested, the originalList will be updated.
ULONG FilterTagItems( struct TagItem * tagList, Tag * filterArray, ULONG logic );
Scans a tag list and removes tag items from the list depending upon whether the tag's Tag value is found in an array of tag values. If 'logic' is TAGFILTER_AND, then all the tags that are NOT in the array filterArray will be removed from the tagList. If 'logic' is TAGFILTER_NOT, then all the tags that ARE in the array filterArray will be removed from the tagList. Tags are removed by setting their ti_Tag value to TAG_IGNORE.
tagList - A TagList to filter items from. filterArray - An array (as described by TagInArray()) to determine which tag items are to be removed. logic - Whether the tags in filterArray are to be included or excluded from the tag list.
The number of valid items left in the resulting filtered list.
struct NamedObject * FindNamedObject( struct NamedObject * nameSpace, CONST_STRPTR name, struct NamedObject * lastObject );
This function will search through a given NameSpace, or the system global NameSpace to find a NamedObject with the name requested. Optionally you can have the search start from a specific NamedObject. This way you can look for each occurence of a specifically named NamedObject in a NameSpace that allows for duplicates.
nameSpace - The NameSpace to search through. If NULL will use the system default NameSpace. name - The name of the object to search for. If NULL, any and all NamedObjects will be matched. lastObject - The (optional) last NamedObject to start the search from.
If a NamedObject with the name supplied exists, it will be returned. Otherwise will return NULL. When you have finised with this NamedObject, you should call ReleaseNamedObject( NamedObject ).
If you are going to use a returned NamedObject to be the starting point for another search you must call ReleaseNamedObject() AFTER searching, as the ReleaseNamedObject() call can cause the NamedObject to be freed, leaving you with an invalid pointer.
struct TagItem * FindTagItem( Tag tagValue, struct TagItem * tagList ); struct TagItem * FindTagItemTags( Tag tagValue, TAG tag, ... );
void FreeNamedObject( struct NamedObject * object );
Frees a NamedObject previously allocated by AllocNamedObject().
object - The NamedObject that you wish to free.
The memory used by the NamedObject will be returned to the systems free memory pool.
void FreeTagItems( struct TagItem * tagList ); void FreeTagItemsTags( TAG tag, ... );
Free a list of TagItems which was allocated by AllocateTagItems().
tagList - A list of TagItems - must have been allocated by AllocateTagItems() or CloneTagItems().
The memory containing the tagList is returned to the system.
struct TagItem *tagList; tagList = AllocateTagItems( 4 ); tagList[0].ti_Tag = NA_Name; tagList[0].ti_Data = (IPTR)"A list of tags"; tagList[3].ti_Tag = TAG_DONE; \* Do what you want with your TagList here ... *\ FreeTagItems( tagList );
The memory will only be freed if the input is non-NULL.
IPTR GetTagData( Tag tagValue, IPTR defaultVal, struct TagItem * tagList ); IPTR GetTagDataTags( Tag tagValue, IPTR defaultVal, TAG tag, ... );
Searches the TagList for the Tag specified, if it exists, then returns the ti_Data field of that Tag, otherwise returns the supplied default value.
tagValue - Tag to search for. defaultVal - Default value for the Tag. tagList - Pointer to first TagItem in the list.
The data value if the Tag exists, or the default value if it doesn't.
struct Window *window; \* The Window we are creating *\ struct TagItem *wintags; \* Tags for this window *\ \* Find out the value for the WA_Left tag *\ window->Left = GetTagData( WA_Left, 320, wintags )
If the input TagList doesn't exist (eg for some reason equals NULL), then the return value will be NULL. This way you can check for broken code, whereas returing the default would allow code that is possibly buggy to still seem to work. (Until you tried to do anything special at least).
ULONG GetUniqueID();
Returns a unique id that is different from any other id that is obtained from this function call.
an unsigned long id
void MapTags( struct TagItem * tagList, struct TagItem * mapList, ULONG mapType );
Replace the ti_Tags in tagList which match the ti_Tags in mapList by the ti_Data values of mapList.
tagList - This list is modified mapList - This defines which ti_Tag is replaced with what new value.
None.
STRPTR NamedObjectName( struct NamedObject * object );
Return the name associated with a NamedObject.
object - The NamedObject you want the name of.
The name of the object will be returned.
struct NamedObject *no; STRPTR name; \* Some other code here *\ name = NamedObjectName( no );
struct TagItem * NextTagItem( struct TagItem ** tagListPtr );
Returns the address of the next tag-item in the list. This routine correctly handles TAG_END, TAG_DONE, TAG_MORE, TAG_IGNORE and TAG_SKIP. TAG_END and TAG_DONE both terminate a TagItems-array (in fact, TAG_DONE is the same as TAG_END). With TAG_MORE, you can redirect the processing to a new list of tags. Note that the processing will not return to the previous list when a TAG_END/TAG_DONE is encountered. TAG_IGNORE disables the processing of an entry in the list. This entry is just ignored (We use this technique for filtering). TAG_SKIP skips this tagitem, and the next number of tagitems as indicated in the tag's ti_Data field.
tagListPtr - Pointer to an element in a taglist.
Next tag item or NULL if you reached the end of the list.
- TAG_MORE works like "go on with new list" instead of "read new list and go on with the current one".
ULONG PackBoolTags( ULONG initialFlags, struct TagItem * tagList, struct TagItem * boolMap ); ULONG PackBoolTagsTags( ULONG initialFlags, struct TagItem * tagList, TAG tag, ... );
Scans through the list tagList to find the tags which are contained in the list boolMap which are then converted to a bit-flag representation as defined in boolMap. If the value of the Tag's data is 0, then the boolean value of the tag is defined as false, otherwise it is true.
initialFlags - an initial set of bit-flags which will be changed by this function. tagList - A TagItem list which contains some tags which are defined as boolean by having a corresponding tag in boolMap. The boolean value of tag->ti_Data determines whether the bits in the flag are TRUE or FALSE. boolMap - A TagItem list containing a series of tags which are to be considered Boolean.
flags - The value of initialFlags modified by the values of the boolean tags defined in boolMap.
If there is more than one Tag in tagList of a single type. The last of these tags will determine the value of that bit-flag.
ULONG PackStructureTags( APTR pack, ULONG * packTable, struct TagItem * tagList ); ULONG PackStructureTagsTags( APTR pack, ULONG * packTable, TAG tag, ... );
This function will scan through the packTable, and for each TagItem described in a packTable entry which can be found in the tagList, the data in the TagItem's ti_Data field will be packed into the structure as described in the packTable.
pack - The structure to fill in. packTable - Table describing how to pack the structure. See the include file utility/pack.h for information on the format of this table. tagList - List of TagItems containing data.
The number of TagItems packed.
void RefreshTagItemClones( struct TagItem * clone, struct TagItem * original ); void RefreshTagItemClonesTags( struct TagItem * clone, TAG tag, ... );
If (and only if) the Tag list 'clone' was created by calling CloneTagItems on the Tag list 'original', and the list original has NOT been changed in any way, then this function will change the list 'clone' back to its original state.
original - The source TagList (unaltered) clone - The destination TagList (MUST be allocated by CloneTagItems())
The second TagList now has the same values as the first.
struct TagItem *orig, clone; \* TagList orig has some values already *\ clone = CloneTagList( orig ); \* In between here we do something to the TagItems in clone, but we need to have them restored. *\ RefreshTagItemClones( clone, orig );
If either of the inputs is NULL, then the function will not do anything.
None, however if either of the two pre-conditions is not fulfilled then this function will probably be unreliable, or trash memory. We warned you...
void ReleaseNamedObject( struct NamedObject * object );
Releases a NamedObject that you previously obtained by calling FindNamedObject.
object - The NamedObject to release.
The NamedObject will be released from your possession, and if it is ready to be deallocated, then the NamedObject will be freed.
struct NamedObject *nObj, *myNameSpace; if( nObj = FindNamedObject( myNameSpace, "Some Name", NULL ) ) { \* Here you do whatever you want. However The NamedObject structure should generally be treated READ-ONLY *\ ReleaseNamedObject( nObj ); }
WARNING: You really should actually have found the NamedObject first (that is with FindNamedObject()) before calling this function. Failure to take heed of this will cause memory use problems.
void RemNamedObject( struct NamedObject * object, struct Message * message );
Remove a NamedObject from a namespace. If the NamedObject cannot be removed at the time of this call, then the call will return without removing the NamedObject. It will mark the NamedObject as "waiting for removal". When the NamedObject is ready to be freed, the supplied message will be ReplyMsg()'d with the message->mn_Node.ln_Name field containing either: - the address of the NamedObject that was removed. In this case you can free the NamedObject yourself. - NULL. In this case, another Task has freed the NamedObject, and you should not do so.
object - The NamedObject to attempt to remove. message - The message to send. This message is a standard Exec Message, which MUST have the mn_ReplyPort field correctly set. The mn_Node.ln_Name field will contain the address of the NamedObject or NULL upon arrival at your port.
The NamedObject will be removed if possible, or marked for removal at the next best moment.
Since this function effectively does a ReleaseNamedObject(), you must have found this object first.
QUAD SDivMod32( LONG dividend, LONG divisor );
Calculates the 32-bit signed division of dividend by divisor. That is dividend / divisor. Will return both the quotient and the remainder.
dividend - The number to divide. divisor - The to divide by.
For m68k assembly programmers: D0: quotient D1: remainder Others: The quotient is returned in the high 32 bits of the result. The remainder in the low 32 bits.
The utility.library math functions are unlike all other utility functions in that they don't require the library base to be loaded in register A6, and they also save the values of the address registers A0/A1. This function is mainly to support assembly programers, and is probably of limited use to higher-level language programmers.
It is very hard for a C programmer to obtain the value of the remainder. In fact, its pretty near impossible.
LONG SMult32( LONG arg1, LONG arg2 );
Performs the signed 32-bit multiplication of arg1 * arg2 and returns a signed 32 bit value.
arg1, arg2 - 32 bit signed longs
arg1 * arg2
LONG a = 352543; LONG b = -52464; LONG c = SMult32(a,b); c == -1315946768
This can perform the multiplication either using the machines native instructions (if they exist), or in software using a simple algorithm based on expanding algebraic products. The utility.library math functions are unlike all other utility functions in that they don't require the library base to be loaded in register A6, and they also save the values of the address registers A0/A1. This function is mainly to support assembly programers, and is probably of limited use to higher-level language programmers.
Of limited use to C programmers.
QUAD SMult64( LONG arg1, LONG arg2 );
Compute the signed 64-bit product of arg1 * arg2.
arg1, arg2 - 32 bit signed numbers.
arg1 * arg2
For m68k assembly programmers, QUADs are returned in D0:D1 (with the high 32 bits in D0). The utility.library math functions are unlike all other utility functions in that they don't require the library base to be loaded in register A6, and they also save the values of the address registers A0/A1. This function is mainly to support assembly programers, and is probably of limited use to higher-level language programmers.
LONG Stricmp( CONST_STRPTR string1, CONST_STRPTR string2 );
Compares two strings treating lower and upper case characters as identical.
string1, string2 - The strings to compare.
<0 if string1 < string2 ==0 if string1 == string2 >0 if string1 > string2
LONG Strnicmp( CONST_STRPTR string1, CONST_STRPTR string2, LONG length );
Compares two strings treating lower and upper case characters as identical up to a given maximum number of characters.
string1, string2 - The strings to compare. length - maximum number of characters to compare.
<0 if string1 < string2 ==0 if string1 == string2 >0 if string1 > string2
BOOL TagInArray( Tag tagValue, Tag * tagArray );
Determines whether the value tagValue exists in an array of Tags pointed to by tagArray. This array must be contiguous, and must be terminated by TAG_DONE. This is an array of Tags (ie: Tag tagArray[]), not an array of TagItems (ie: struct TagItem tagArray[]).
tagValue - The value of the Tag to search for. tagArray - The ARRAY of Tag's to scan through.
TRUE if tagValue exists in tagArray FALSE otherwise
UBYTE ToLower( ULONG character );
Convert a character to lower case.
character - The character to convert.
Equivalent lower case character.
UBYTE ToUpper( ULONG character );
Convert a character to uppercase
character - The character that you want changed.
The uppercase version of that character.
STRPTR string; UBYTE chr; \* Convert a string to uppercase *\ while( chr = *string ) { *string = ToUpper( chr ); string++; }
Currently only works for ASCII characters. Would not be difficult to adapt for other character sets (Unicode for example). This function is patched by the locale.library, so you should be prepared for different results when running under different languages.
ULONG UDivMod32( ULONG dividend, ULONG divisor );
Perform the 32 bit unsigned division and modulus of dividend by divisor, that is dividend / divisor. Will return both the quotient and the remainder.
dividend - The number to divide into (numerator). divisor - The number to divide by (denominator).
For m68k assembly programmers, D0: quotient D1: remainder For HLL programmers, the quotient
The utility.library math functions are unlike all other utility functions in that they don't require the library base to be loaded in register A6, and they also save the values of the address registers A0/A1. This function is mainly to support assembly programers, and is probably of limited use to higher-level language programmers.
It is impossible for C programmers to obtain the value of remainder.
ULONG UMult32( ULONG arg1, ULONG arg2 );
Performs an unsigned 32-bit multiplication of arg1 * arg2 and returns a 32 bit value.
arg1, arg2 - 32 bit unsigned longs
arg1 * arg2
LONG a = 352543; LONG b = 52464; LONG c = UMult32(a,b); c == 1315946768
This can perform the multiplication either using the machines native instructions (if they exist), or in software using a simple algorithm (three multiplications, two shifts and an addition. The utility.library math functions are unlike all other utility functions in that they don't require the library base to be loaded in register A6, and they also save the values of the address registers A0/A1. This function is mainly to support assembly programers, and is probably of limited use to higher-level language programmers.
UQUAD UMult64( ULONG arg1, ULONG arg2 );
Compute the unsigned 64-bit product of arg1 * arg2.
arg1, arg2 - 32 bit unsigned numbers.
arg1 * arg2
For m68k assembly programmers, UQUADs are returned in D0:D1 (with the high 32 bits in D0. This function is really only for people programming in assembly on real Amigas. Most compilers will be able to do this math for you inline.
ULONG UnpackStructureTags( APTR pack, ULONG * packTable, struct TagItem * tagList ); ULONG UnpackStructureTagsTags( APTR pack, ULONG * packTable, TAG tag, ... );
For each table entry, if the matching tag is found in the tagList, then the data in the structure will be placed in the memory pointed to by the tags ti_Data. Note: The value contained in ti_Data must be a *POINTER* to a IPTR.
pack - Pointer to the memory area to be unpacked. packTable - Table describing the unpacking operation. See the include file <utility/pack.h> for more information on this table. tagList - List of TagItems to unpack into.
The number of Tags unpacked.
PSTF_EXISTS has no effect on this function.