gnome-vfs-mime-database-deprecated

gnome-vfs-mime-database-deprecated —

Synopsis




enum        GnomeVFSMimeActionType;
enum        GnomeVFSMimeApplicationArgumentType;
            GnomeVFSMimeAction;
GnomeVFSMimeActionType gnome_vfs_mime_get_default_action_type
                                            (const char *mime_type);
GnomeVFSMimeAction* gnome_vfs_mime_get_default_action
                                            (const char *mime_type);
GList*      gnome_vfs_mime_get_short_list_applications
                                            (const char *mime_type);
GList*      gnome_vfs_mime_get_short_list_components
                                            (const char *mime_type);
GnomeVFSResult gnome_vfs_mime_set_default_action_type
                                            (const char *mime_type,
                                             GnomeVFSMimeActionType action_type);
GnomeVFSResult gnome_vfs_mime_set_icon      (const char *mime_type,
                                             const char *filename);
GnomeVFSResult gnome_vfs_mime_set_description
                                            (const char *mime_type,
                                             const char *description);
GnomeVFSResult gnome_vfs_mime_set_can_be_executable
                                            (const char *mime_type,
                                             gboolean new_value);
GnomeVFSResult gnome_vfs_mime_set_short_list_applications
                                            (const char *mime_type,
                                             GList *application_ids);
GnomeVFSResult gnome_vfs_mime_set_short_list_components
                                            (const char *mime_type,
                                             GList *component_iids);
GnomeVFSResult gnome_vfs_mime_add_application_to_short_list
                                            (const char *mime_type,
                                             const char *application_id);
GnomeVFSResult gnome_vfs_mime_remove_application_from_short_list
                                            (const char *mime_type,
                                             const char *application_id);
GnomeVFSResult gnome_vfs_mime_add_component_to_short_list
                                            (const char *mime_type,
                                             const char *iid);
GnomeVFSResult gnome_vfs_mime_remove_component_from_short_list
                                            (const char *mime_type,
                                             const char *iid);
GnomeVFSResult gnome_vfs_mime_add_extension (const char *mime_type,
                                             const char *extension);
GnomeVFSResult gnome_vfs_mime_remove_extension
                                            (const char *mime_type,
                                             const char *extension);
GnomeVFSResult gnome_vfs_mime_extend_all_applications
                                            (const char *mime_type,
                                             GList *application_ids);
GnomeVFSResult gnome_vfs_mime_remove_from_all_applications
                                            (const char *mime_type,
                                             GList *application_ids);
GnomeVFSMimeApplication* gnome_vfs_mime_application_new_from_id
                                            (const char *id);
void        gnome_vfs_mime_action_free      (GnomeVFSMimeAction *action);
gboolean    gnome_vfs_mime_id_in_application_list
                                            (const char *id,
                                             GList *applications);
gboolean    gnome_vfs_mime_id_in_component_list
                                            (const char *iid,
                                             GList *components);
GList*      gnome_vfs_mime_remove_application_from_list
                                            (GList *applications,
                                             const char *application_id,
                                             gboolean *did_remove);
GList*      gnome_vfs_mime_remove_component_from_list
                                            (GList *components,
                                             const char *iid,
                                             gboolean *did_remove);
GList*      gnome_vfs_mime_id_list_from_component_list
                                            (GList *components);
GList*      gnome_vfs_mime_id_list_from_application_list
                                            (GList *applications);
void        gnome_vfs_mime_freeze           (void);
void        gnome_vfs_mime_thaw             (void);
void        gnome_vfs_mime_info_reload      (void);
gboolean    gnome_vfs_mime_type_is_known    (const char *mime_type);
const char* gnome_vfs_mime_get_value        (const char *mime_type,
                                             const char *key);
GnomeVFSResult gnome_vfs_mime_set_value     (const char *mime_type,
                                             const char *key,
                                             const char *value);
GList*      gnome_vfs_mime_get_key_list     (const char *mime_type);
void        gnome_vfs_mime_keys_list_free   (GList *mime_type_list);
GList*      gnome_vfs_mime_get_extensions_list
                                            (const char *mime_type);
void        gnome_vfs_mime_extensions_list_free
                                            (GList *list);
char*       gnome_vfs_mime_get_extensions_string
                                            (const char *mime_type);
char*       gnome_vfs_mime_get_extensions_pretty_string
                                            (const char *mime_type);
GList*      gnome_vfs_get_registered_mime_types
                                            (void);
void        gnome_vfs_mime_registered_mime_type_list_free
                                            (GList *list);
GnomeVFSResult gnome_vfs_mime_set_registered_type_key
                                            (const char *mime_type,
                                             const char *key,
                                             const char *data);
GnomeVFSResult gnome_vfs_mime_set_extensions_list
                                            (const char *mime_type,
                                             const char *extensions_list);
void        gnome_vfs_mime_registered_mime_type_delete
                                            (const char *mime_type);
void        gnome_vfs_mime_reset            (void);

Description

Details

enum GnomeVFSMimeActionType

typedef enum {
	GNOME_VFS_MIME_ACTION_TYPE_NONE,
	GNOME_VFS_MIME_ACTION_TYPE_APPLICATION,
	GNOME_VFS_MIME_ACTION_TYPE_COMPONENT
} GnomeVFSMimeActionType;

Warning

GnomeVFSMimeActionType is deprecated and should not be used in newly-written code.


enum GnomeVFSMimeApplicationArgumentType

typedef enum {
	GNOME_VFS_MIME_APPLICATION_ARGUMENT_TYPE_URIS,
	GNOME_VFS_MIME_APPLICATION_ARGUMENT_TYPE_PATHS,
	GNOME_VFS_MIME_APPLICATION_ARGUMENT_TYPE_URIS_FOR_NON_FILES
} GnomeVFSMimeApplicationArgumentType;


GnomeVFSMimeAction

typedef struct {
	GnomeVFSMimeActionType action_type;
	union {
		Bonobo_ServerInfo *component;
		void *dummy_component;
		GnomeVFSMimeApplication *application;
} GnomeVFSMimeAction;

Warning

GnomeVFSMimeAction is deprecated and should not be used in newly-written code.

This data structure describes an action that can be done on a file.


gnome_vfs_mime_get_default_action_type ()

GnomeVFSMimeActionType gnome_vfs_mime_get_default_action_type
                                            (const char *mime_type);

Warning

gnome_vfs_mime_get_default_action_type is deprecated and should not be used in newly-written code.

Query the MIME database for the type of action to be performed on a particular MIME type by default.

mime_type : A const char * containing a mime type, e.g. "application/x-php"
Returns : The type of action to be performed on a file of MIME type, mime_type by default.

gnome_vfs_mime_get_default_action ()

GnomeVFSMimeAction* gnome_vfs_mime_get_default_action
                                            (const char *mime_type);

Warning

gnome_vfs_mime_get_default_action is deprecated and should not be used in newly-written code.

Query the MIME database for default action associated with a particular MIME type mime_type.

mime_type : A const char * containing a mime type, e.g. "application/x-php"
Returns : A GnomeVFSMimeAction representing the default action to perform upon file of type mime_type.

gnome_vfs_mime_get_short_list_applications ()

GList*      gnome_vfs_mime_get_short_list_applications
                                            (const char *mime_type);

Warning

gnome_vfs_mime_get_short_list_applications is deprecated and should not be used in newly-written code.

Return an alphabetically sorted list of GnomeVFSMimeApplication data structures for the requested mime type. GnomeVFS no longer supports the concept of a "short list" of applications that the user might be interested in.

mime_type : A const char * containing a mime type, e.g. "image/png"
Returns : A GList * where the elements are GnomeVFSMimeApplication * representing various applications to display in the short list for mime_type. Deprecated: Use gnome_vfs_mime_get_all_applications() instead.

gnome_vfs_mime_get_short_list_components ()

GList*      gnome_vfs_mime_get_short_list_components
                                            (const char *mime_type);

Warning

gnome_vfs_mime_get_short_list_components is deprecated and should not be used in newly-written code.

Return an unsorted sorted list of Bonobo_ServerInfo * data structures for the requested mime type. GnomeVFS no longer supports the concept of a "short list" of applications that the user might be interested in.

mime_type : A const char * containing a mime type, e.g. "image/png"
Returns : A GList * where the elements are Bonobo_ServerInfo * representing various components to display in the short list for mime_type. Deprecated: Use gnome_vfs_mime_get_all_components() instead.

gnome_vfs_mime_set_default_action_type ()

GnomeVFSResult gnome_vfs_mime_set_default_action_type
                                            (const char *mime_type,
                                             GnomeVFSMimeActionType action_type);

Warning

gnome_vfs_mime_set_default_action_type is deprecated and should not be used in newly-written code.

Sets the default action type to be performed on files of MIME type mime_type.

mime_type : A const char * containing a mime type, e.g. "image/png"
action_type : A GnomeVFSMimeActionType containing the action to perform by default
Returns : A GnomeVFSResult indicating the success of the operation or reporting any errors encountered.

gnome_vfs_mime_set_icon ()

GnomeVFSResult gnome_vfs_mime_set_icon      (const char *mime_type,
                                             const char *filename);

Warning

gnome_vfs_mime_set_icon is deprecated and should not be used in newly-written code.

Set the icon entry for a particular MIME type in the MIME database. Note that icon entries need not necessarily contain the full path, and do not necessarily need to specify an extension. So "i-regular", "my-special-icon.png", and "some-icon" are all valid icon filenames.

mime_type : A const char * containing a MIME type
filename : a const char * containing an image filename
Returns : A GnomeVFSResult indicating the success of the operation or any errors that may have occurred.

gnome_vfs_mime_set_description ()

GnomeVFSResult gnome_vfs_mime_set_description
                                            (const char *mime_type,
                                             const char *description);

Warning

gnome_vfs_mime_set_description is deprecated and should not be used in newly-written code.

Set the description of this MIME type in the MIME database. The description should be something like "Gnumeric spreadsheet".

mime_type : A const char * containing a mime type
description : A description of this MIME type
Returns : GnomeVFSResult indicating the success of the operation or any errors that may have occurred.

gnome_vfs_mime_set_can_be_executable ()

GnomeVFSResult gnome_vfs_mime_set_can_be_executable
                                            (const char *mime_type,
                                             gboolean new_value);

Warning

gnome_vfs_mime_set_can_be_executable is deprecated and should not be used in newly-written code.

Set whether files of this MIME type might conceivably be executable.

mime_type : A const char * containing a mime type
new_value : A boolean value indicating whether mime_type could be executable.
Returns : GnomeVFSResult indicating the success of the operation or any errors that may have occurred.

gnome_vfs_mime_set_short_list_applications ()

GnomeVFSResult gnome_vfs_mime_set_short_list_applications
                                            (const char *mime_type,
                                             GList *application_ids);

Warning

gnome_vfs_mime_set_short_list_applications is deprecated and should not be used in newly-written code.

Set the short list of applications for the specified MIME type. The short list contains applications recommended for possible selection by the user.

mime_type : A const char * containing a mime type, e.g. "application/x-php"
application_ids : GList of const char * application ids
Returns : A GnomeVFSResult indicating the success of the operation or reporting any errors encountered.

gnome_vfs_mime_set_short_list_components ()

GnomeVFSResult gnome_vfs_mime_set_short_list_components
                                            (const char *mime_type,
                                             GList *component_iids);

Warning

gnome_vfs_mime_set_short_list_components is deprecated and should not be used in newly-written code.

Set the short list of components for the specified MIME type. The short list contains companents recommended for possible selection by the user. *

mime_type : A const char * containing a mime type, e.g. "application/x-php"
component_iids : GList of const char * OAF IIDs
Returns : A GnomeVFSResult indicating the success of the operation or reporting any errors encountered.

gnome_vfs_mime_add_application_to_short_list ()

GnomeVFSResult gnome_vfs_mime_add_application_to_short_list
                                            (const char *mime_type,
                                             const char *application_id);

Warning

gnome_vfs_mime_add_application_to_short_list is deprecated and should not be used in newly-written code.

Add an application to the short list for MIME type mime_type. The short list contains applications recommended for display as choices to the user for a particular MIME type.

mime_type : A const char * containing a mime type, e.g. "application/x-php"
application_id : const char * containing the application's id in the MIME database
Returns : A GnomeVFSResult indicating the success of the operation or reporting any errors encountered.

gnome_vfs_mime_remove_application_from_short_list ()

GnomeVFSResult gnome_vfs_mime_remove_application_from_short_list
                                            (const char *mime_type,
                                             const char *application_id);

Warning

gnome_vfs_mime_remove_application_from_short_list is deprecated and should not be used in newly-written code.

Remove an application from the short list for MIME type mime_type. The short list contains applications recommended for display as choices to the user for a particular MIME type.

mime_type : A const char * containing a mime type, e.g. "application/x-php"
application_id : const char * containing the application's id in the MIME database
Returns : A GnomeVFSResult indicating the success of the operation or reporting any errors encountered.

gnome_vfs_mime_add_component_to_short_list ()

GnomeVFSResult gnome_vfs_mime_add_component_to_short_list
                                            (const char *mime_type,
                                             const char *iid);

Warning

gnome_vfs_mime_add_component_to_short_list is deprecated and should not be used in newly-written code.

Add a component to the short list for MIME type mime_type. The short list contains components recommended for display as choices to the user for a particular MIME type.

mime_type : A const char * containing a mime type, e.g. "application/x-php"
iid : const char * containing the component's OAF IID
Returns : A GnomeVFSResult indicating the success of the operation or reporting any errors encountered.

gnome_vfs_mime_remove_component_from_short_list ()

GnomeVFSResult gnome_vfs_mime_remove_component_from_short_list
                                            (const char *mime_type,
                                             const char *iid);

Warning

gnome_vfs_mime_remove_component_from_short_list is deprecated and should not be used in newly-written code.

Remove a component from the short list for MIME type mime_type. The short list contains components recommended for display as choices to the user for a particular MIME type.

mime_type : A const char * containing a mime type, e.g. "application/x-php"
iid : const char * containing the component's OAF IID
Returns : A GnomeVFSResult indicating the success of the operation or reporting any errors encountered.

gnome_vfs_mime_add_extension ()

GnomeVFSResult gnome_vfs_mime_add_extension (const char *mime_type,
                                             const char *extension);

Warning

gnome_vfs_mime_add_extension is deprecated and should not be used in newly-written code.

Add a file extension to the specificed MIME type in the MIME database.

mime_type : The mime type to add the mapping to.
extension : The extension to add (e.g. "txt")
Returns : GnomeVFSResult indicating the success of the operation or any errors that may have occurred.

gnome_vfs_mime_remove_extension ()

GnomeVFSResult gnome_vfs_mime_remove_extension
                                            (const char *mime_type,
                                             const char *extension);

Warning

gnome_vfs_mime_remove_extension is deprecated and should not be used in newly-written code.

Removes a file extension from the specificed MIME type in the MIME database.

mime_type : The mime type to remove the extension from
extension : The extension to remove
Returns : GnomeVFSResult indicating the success of the operation or any errors that may have occurred.

gnome_vfs_mime_extend_all_applications ()

GnomeVFSResult gnome_vfs_mime_extend_all_applications
                                            (const char *mime_type,
                                             GList *application_ids);

Warning

gnome_vfs_mime_extend_all_applications is deprecated and should not be used in newly-written code.

Register mime_type as being handled by all applications list in application_ids.

mime_type : A const char * containing a mime type, e.g. "application/x-php"
application_ids : a GList of const char * containing application ids
Returns : A GnomeVFSResult indicating the success of the operation or reporting any errors encountered.

gnome_vfs_mime_remove_from_all_applications ()

GnomeVFSResult gnome_vfs_mime_remove_from_all_applications
                                            (const char *mime_type,
                                             GList *application_ids);

Warning

gnome_vfs_mime_remove_from_all_applications is deprecated and should not be used in newly-written code.

Remove mime_type as a handled type from every application in application_ids

mime_type : A const char * containing a mime type, e.g. "application/x-php"
application_ids : a GList of const char * containing application ids
Returns : A GnomeVFSResult indicating the success of the operation or reporting any errors encountered.

gnome_vfs_mime_application_new_from_id ()

GnomeVFSMimeApplication* gnome_vfs_mime_application_new_from_id
                                            (const char *id);

Warning

gnome_vfs_mime_application_new_from_id is deprecated and should not be used in newly-written code.

Fetches the GnomeVFSMimeApplication associated with the specified application ID from the MIME database.

id : A const char * containing an application id
Returns : GnomeVFSMimeApplication * corresponding to id

gnome_vfs_mime_action_free ()

void        gnome_vfs_mime_action_free      (GnomeVFSMimeAction *action);

Warning

gnome_vfs_mime_action_free is deprecated and should not be used in newly-written code.

Frees a GnomeVFSMimeAction *.

action : The GnomeVFSMimeAction to be freed

gnome_vfs_mime_id_in_application_list ()

gboolean    gnome_vfs_mime_id_in_application_list
                                            (const char *id,
                                             GList *applications);

Warning

gnome_vfs_mime_id_in_application_list is deprecated and should not be used in newly-written code.

Check whether an application id is in a list of GnomeVFSMimeApplications.

id : An application id.
applications : A GList * whose nodes are GnomeVFSMimeApplications, such as the result of gnome_vfs_mime_get_short_list_applications().
Returns : TRUE if an application whose id matches id is in applications.

gnome_vfs_mime_id_in_component_list ()

gboolean    gnome_vfs_mime_id_in_component_list
                                            (const char *iid,
                                             GList *components);

Warning

gnome_vfs_mime_id_in_component_list is deprecated and should not be used in newly-written code.

Check whether a component iid is in a list of Bonobo_ServerInfos.

iid : A component iid.
components : A GList * whose nodes are Bonobo_ServerInfos, such as the result of gnome_vfs_mime_get_short_list_components().
Returns : TRUE if a component whose iid matches iid is in components.

gnome_vfs_mime_remove_application_from_list ()

GList*      gnome_vfs_mime_remove_application_from_list
                                            (GList *applications,
                                             const char *application_id,
                                             gboolean *did_remove);

Warning

gnome_vfs_mime_remove_application_from_list is deprecated and should not be used in newly-written code.

Remove an application specified by id from a list of GnomeVFSMimeApplications.

applications : A GList * whose nodes are GnomeVFSMimeApplications, such as the result of gnome_vfs_mime_get_short_list_applications().
application_id : The id of an application to remove from applications.
did_remove : If non-NULL, this is filled in with TRUE if the application was found in the list, FALSE otherwise.
Returns : The modified list. If the application is not found, the list will be unchanged.

gnome_vfs_mime_remove_component_from_list ()

GList*      gnome_vfs_mime_remove_component_from_list
                                            (GList *components,
                                             const char *iid,
                                             gboolean *did_remove);

Warning

gnome_vfs_mime_remove_component_from_list is deprecated and should not be used in newly-written code.

Remove a component specified by iid from a list of Bonobo_ServerInfos.

components : A GList * whose nodes are Bonobo_ServerInfos, such as the result of gnome_vfs_mime_get_short_list_components().
iid : The iid of a component to remove from components.
did_remove : If non-NULL, this is filled in with TRUE if the component was found in the list, FALSE otherwise.
Returns : The modified list. If the component is not found, the list will be unchanged.

gnome_vfs_mime_id_list_from_component_list ()

GList*      gnome_vfs_mime_id_list_from_component_list
                                            (GList *components);

Warning

gnome_vfs_mime_id_list_from_component_list is deprecated and should not be used in newly-written code.

Create a list of component iids from a list of Bonobo_ServerInfos.

components : A GList * whose nodes are Bonobo_ServerInfos, such as the result of gnome_vfs_mime_get_short_list_components().
Returns : A new list where each Bonobo_ServerInfo in the original list is replaced by a char * with the component's iid. The original list is not modified.

gnome_vfs_mime_id_list_from_application_list ()

GList*      gnome_vfs_mime_id_list_from_application_list
                                            (GList *applications);

Warning

gnome_vfs_mime_id_list_from_application_list is deprecated and should not be used in newly-written code.

Create a list of application ids from a list of GnomeVFSMimeApplications.

applications : A GList * whose nodes are GnomeVFSMimeApplications, such as the result of gnome_vfs_mime_get_short_list_applications().
Returns : A new list where each GnomeVFSMimeApplication in the original list is replaced by a char * with the application's id. The original list is not modified.

gnome_vfs_mime_freeze ()

void        gnome_vfs_mime_freeze           (void);

Freezes the mime data so that you can do multiple updates to the dat in one batch without needing to back the files to disk or readind them


gnome_vfs_mime_thaw ()

void        gnome_vfs_mime_thaw             (void);

UnFreezes the mime data so that you can do multiple updates to the dat in one batch without needing to back the files to disk or readind them


gnome_vfs_mime_info_reload ()

void        gnome_vfs_mime_info_reload      (void);

Reload the MIME database from disk and notify any listeners holding active GnomeVFSMIMEMonitor objects.


gnome_vfs_mime_type_is_known ()

gboolean    gnome_vfs_mime_type_is_known    (const char *mime_type);

This function returns TRUE if mime_type is in the MIME database at all.

mime_type : a mime type.
Returns : TRUE if anything is known about mime_type, otherwise FALSE

gnome_vfs_mime_get_value ()

const char* gnome_vfs_mime_get_value        (const char *mime_type,
                                             const char *key);

This function retrieves the value associated with key in the given GnomeMimeContext. The string is private, you should not free the result.

mime_type : a mime type.
key : A key to lookup for the given mime-type
Returns : GNOME_VFS_OK if the operation succeeded, otherwise an error code

gnome_vfs_mime_set_value ()

GnomeVFSResult gnome_vfs_mime_set_value     (const char *mime_type,
                                             const char *key,
                                             const char *value);

This function is going to set the value associated to the key and it will save it to the user' file if necessary. You should not free the key/values passed to this function. They are used internally.

mime_type : a mime type.
key : a key to store the value in.
value : the value to store in the key.
Returns : GNOME_VFS_OK if the operation succeeded, otherwise an error code

gnome_vfs_mime_get_key_list ()

GList*      gnome_vfs_mime_get_key_list     (const char *mime_type);

Warning

gnome_vfs_mime_get_key_list is deprecated and should not be used in newly-written code.

mime_type :
Returns :

gnome_vfs_mime_keys_list_free ()

void        gnome_vfs_mime_keys_list_free   (GList *mime_type_list);

Warning

gnome_vfs_mime_keys_list_free is deprecated and should not be used in newly-written code.

mime_type_list :

gnome_vfs_mime_get_extensions_list ()

GList*      gnome_vfs_mime_get_extensions_list
                                            (const char *mime_type);

Get the file extensions associated with mime type mime_type.

mime_type : type to get the extensions of
Returns : a GList of char *s

gnome_vfs_mime_extensions_list_free ()

void        gnome_vfs_mime_extensions_list_free
                                            (GList *list);

Call this function on the list returned by gnome_vfs_mime_extensions to free the list and all of its elements.

list : the extensions list

gnome_vfs_mime_get_extensions_string ()

char*       gnome_vfs_mime_get_extensions_string
                                            (const char *mime_type);

Warning

gnome_vfs_mime_get_extensions_string is deprecated and should not be used in newly-written code.

mime_type :
Returns :

gnome_vfs_mime_get_extensions_pretty_string ()

char*       gnome_vfs_mime_get_extensions_pretty_string
                                            (const char *mime_type);

Warning

gnome_vfs_mime_get_extensions_pretty_string is deprecated and should not be used in newly-written code.

mime_type :
Returns :

gnome_vfs_get_registered_mime_types ()

GList*      gnome_vfs_get_registered_mime_types
                                            (void);

Warning

gnome_vfs_get_registered_mime_types is deprecated and should not be used in newly-written code.

Returns :

gnome_vfs_mime_registered_mime_type_list_free ()

void        gnome_vfs_mime_registered_mime_type_list_free
                                            (GList *list);

Warning

gnome_vfs_mime_registered_mime_type_list_free is deprecated and should not be used in newly-written code.

list :

gnome_vfs_mime_set_registered_type_key ()

GnomeVFSResult gnome_vfs_mime_set_registered_type_key
                                            (const char *mime_type,
                                             const char *key,
                                             const char *data);

mime_type :
key :
data :
Returns :

gnome_vfs_mime_set_extensions_list ()

GnomeVFSResult gnome_vfs_mime_set_extensions_list
                                            (const char *mime_type,
                                             const char *extensions_list);

Warning

gnome_vfs_mime_set_extensions_list is deprecated and should not be used in newly-written code.

mime_type :
extensions_list :
Returns :

gnome_vfs_mime_registered_mime_type_delete ()

void        gnome_vfs_mime_registered_mime_type_delete
                                            (const char *mime_type);

Warning

gnome_vfs_mime_registered_mime_type_delete is deprecated and should not be used in newly-written code.

mime_type :

gnome_vfs_mime_reset ()

void        gnome_vfs_mime_reset            (void);

Warning

gnome_vfs_mime_reset is deprecated and should not be used in newly-written code.