The first argument of the functions in this interface is usually the tag of the folder to be operated upon. Input arguments always precede output arguments. Therefore, in the case of create, the tag is the last argument.
This module implements the methods of class Folder. The operations you can perform on a folder are:
A folder is accessible in memory after:
Folders are maintained in memory under all the supported sort criteria, it is therefore necessary for the client to specify the criteria. Ordering ascending/descending is not supported since all the client has to do is read the returned array backwards/forwards.
Restrictions:
All entries in a folder must be WorkspaceObjects.
Common Return Values
CXPOM_invalid_tag - Invalid tag passed in.
| typedef enum FL_sort_criteria_e FL_sort_criteria_t |
| typedef enum FL_sort_order_e FL_sort_order_t |
| enum FL_sort_criteria_e |
| enum FL_sort_order_e |
| TC_API int FL_ask_index | ( | tag_t | folder_tag, | |
| tag_t | workspaceobject_tag, | |||
| FL_sort_criteria_t | sort_criteria, | |||
| int * | ref_index | |||
| ) |
Returns the index of a reference based on the sort criteria.
| folder_tag | (I) |
| workspaceobject_tag | (I) |
| sort_criteria | (I) |
| ref_index | (O) |
| TC_API int FL_ask_references | ( | tag_t | folder_tag, | |
| FL_sort_criteria_t | sort_criteria, | |||
| int * | num_of_references, | |||
| tag_t ** | list_of_references | |||
| ) |
Returns a list containing all the references in the folder by the given sort criteria. The client passes in an address to a pointer. This pointer is then assigned an allocated piece of memory that should subsequently be freed by calling MEM_free. Folders are maintained in memory under all the supported sort criteria. It is therefore necessary for the client to specify the criteria.
| folder_tag | (I) |
| sort_criteria | (I) |
| num_of_references | (O) |
| list_of_references | (OF) num_of_references |
| TC_API int FL_ask_size | ( | tag_t | folder_tag, | |
| int * | number_of_entries | |||
| ) |
Returns the number of entries inside a folder.
| folder_tag | (I) |
| number_of_entries | (O) |
| TC_API int FL_ask_sort_criteria | ( | tag_t | folder_tag, | |
| FL_sort_criteria_t * | sort_criteria | |||
| ) |
Gets the sort criteria attribute of the folder specified by folder_tag.
| folder_tag | (I) |
| sort_criteria | (O) |
| TC_API int FL_ask_sort_order | ( | tag_t | folder_tag, | |
| FL_sort_order_t * | sort_order | |||
| ) |
Gets the sort order attribute of the folder specified by folder_tag.
| folder_tag | (I) |
| sort_order | (O) |
| TC_API int FL_copy | ( | tag_t | folder_tag, | |
| const char | new_folder_name[WSO_name_size_c+1], | |||
| tag_t * | new_folder_tag | |||
| ) |
| folder_tag | (I) |
| new_folder_name | (I) |
| new_folder_tag | (O) |
Saves a copy of an existing folder to a new name as specified.
| folder_tag | (I) |
| new_folder_name | (I) |
| new_folder_tag | (O) |
| TC_API int FL_create | ( | const char | name[WSO_name_size_c+1], | |
| const char | description[WSO_desc_size_c+1], | |||
| tag_t * | pfolder_tag | |||
| ) |
| name | (I) |
| description | (I) |
| pfolder_tag | (O) |
| TC_API int FL_exit_module | ( | ) |
Cleans up and exits the Folder module. This function should be called after all FL activity is complete. This function is implicitly called when you call ITK_init_module.
| TC_API int FL_extent | ( | int * | num_of_folders, | |
| tag_t ** | ppfolder_tags | |||
| ) |
Allocates an array of tags and stores in the array all folders in the database. The client is responsible for deallocating the array of folder_tags. Use MEM_free to free the memory pointed to by folder_tags.
Restrictions:
To examine or manipulate the attributes of a folder with the tag returned from this function, you must have the proper access rights to the folder.
| num_of_folders | (O) Stores the size of the array |
| ppfolder_tags | (OF) num_of_folders Points to the array of tags |
| TC_API int FL_init_module | ( | ) |
Phase out of bad names Initializes the folder module. You must call this function before calling any other FL functions.
This function is implicitly called when you call ITK_init_module.
| TC_API int FL_initialize | ( | tag_t | folder_tag, | |
| const char | name[WSO_name_size_c+1], | |||
| const char | description[WSO_desc_size_c+1] | |||
| ) |
You normally use this function with a subclass of Folder. For example, if you defined a class special Folder, you would first call POM_create_instance to create the object in memory. Then you would use this function to initialize the attributes which were inherited from Folder. Finally, you would use additional POM calls to initialize the attributes comprising your specialization of Folder.
| folder_tag | (I) |
| name | (I) |
| description | (I) |
| TC_API int FL_initialize2 | ( | tag_t | folder_tag, | |
| const char * | name, | |||
| const char * | description | |||
| ) |
Initializes a Folder object. It is not saved to the database until an explicit call to AOM_save occurs. You must specify a name and description.
You normally use this function with a subclass of Folder. For example, if you defined a class special Folder, you would first call POM_create_instance to create the object in memory. Then you would use this function to initialize the attributes which were inherited from Folder. Finally, you would use additional POM calls to initialize the attributes comprising your specialization of Folder.
| folder_tag | (I) |
| name | (I) |
| description | (I) |
The following functions manipulate the attributes of a folder in memory. Inserts an object reference into a folder at a specified index position. The third argument "position" is zero based index, and that the input is larger than the number of objects in the folder, or using 999 to indicate the last position.
| folder_tag | (I) Folder where the object will be inserted |
| workspaceobject_tag | (I) the object to be inserted |
| position | (I) |
| TC_API int FL_insert_instances | ( | tag_t | folder_tag, | |
| int | nInstances, | |||
| tag_t * | workspaceobject_tags, | |||
| int | position | |||
| ) |
Inserts more than one object reference into a folder at a specified index position. This function should be used when adding multiple object references at one time.
| folder_tag | (I) Folder where object reference will be placed |
| nInstances | (I) Number of object references to be inserted |
| workspaceobject_tags | (I) nInstances Object references |
| position | (I) |
| TC_API int FL_move | ( | tag_t | folder_tag, | |
| int | old_start_index, | |||
| int | old_end_index, | |||
| int | new_start_index | |||
| ) |
Moves a block of references from one position to another in the folder. Indexes are relative to zero (0). The range old_start_index to old_end_index is inclusive. The range is always inserted above the new_start_index (position in table). All indexes are relative to the original array. You can visualize the references and indexes as a two dimensional table consisting of values that reference objects and indexes that point to one of the values. Your original table might look like the following:
| Value | Index |
| a | 0 |
| b | 1 |
| c | 2 |
| d | 3 |
| e | 4 |
| f | 5 |
If you consider the ordered triplet of integers, (old_start_index, old_end_index, new_start_index), and pass the following values as arguments (2,4,1), then you would be specifying the range of index numbers 2, 3, 4 and a starting index of 1. This means you would move the reference values c, d, and e above the value b. Your resultant table would look like the following:
| Value | Index |
| a | 0 |
| c | 1 |
| d | 2 |
| e | 3 |
| b | 4 |
| f | 5 |
| folder_tag | (I) |
| old_start_index | (I) |
| old_end_index | (I) |
| new_start_index | (I) |
Removes a reference (specified by workspaceobject_tag) from a folder (specified by folder_tag).
| folder_tag | (I) |
| workspaceobject_tag | (I) |
| TC_API int FL_set_sort_criteria | ( | tag_t | folder_tag, | |
| FL_sort_criteria_t | sort_criteria | |||
| ) |
Sets the sort criteria attribute of the folder specified by folder_tag.
| folder_tag | (I) |
| sort_criteria | (I) |
| TC_API int FL_set_sort_order | ( | tag_t | folder_tag, | |
| FL_sort_order_t | sort_order | |||
| ) |
Sets the sort order attribute of the folder specified by folder_tag.
| folder_tag | (I) |
| sort_order | (I) |
| TC_API int FL_user_update_newstuff_folder | ( | tag_t | folder_tag | ) |
This function inserts the specified workspaceobject_tag into the current user's Newstuff folder.
| folder_tag | (I) |