os::RegistrarManager Class Reference
[The Syllable high level filesystem API]

Class to access the registrar server. More...

Inheritance diagram for os::RegistrarManager:

List of all members.

Public Member Functions
	RegistrarManager ()
	Constructor.
	~RegistrarManager ()
	Destructor.
void	AddRef ()
void	Put (bool bAll=false)
	Decrements the reference counter of the instance.
void	HandleMessage (Message *pcMessage)
	Handle a message targeted at this handler.
void	SetSynchronousMode (bool bSync)
	Sets whether the registrar manager class is in synchronous mode.
status_t	RegisterType (String zMimeType, String zIdentifier, bool bOverwrite=false)
	Registers a new filetype.
status_t	UnregisterType (String zMimeType)
	Unregisters a filetype.
status_t	RegisterTypeIcon (String zMimeType, Path cIcon, bool bOverwrite=false)
	Sets a new icon for a filetype.
status_t	RegisterTypeIconFromRes (String zMimeType, String zIconRes, bool bOverwrite=false)
	Sets a new icon for a filetype which will be extracted from the application resources.
status_t	RegisterTypeExtension (String zMimeType, String zExtension)
	Registers a new extension for a type.
status_t	ClearTypeExtensions (String zMimeType)
	Clears the extension list for a type.
status_t	RegisterTypeHandler (String zMimeType, Path cHandler)
	Registers a new handler for a type.
status_t	RegisterAsTypeHandler (String zMimeType)
	Registers the current application as a handler for a type.
status_t	ClearTypeHandlers (String zMimeType)
	Clears the handler list for a type.
int32	GetTypeCount ()
	Returns the number of types that are registered for the calling user.
RegistrarFileType	GetType (int32 nIndex)
	Returns a RegistrarFileType object that describes a specific type.
status_t	SetDefaultHandler (String zMimeType, Path zHandler)
	Sets the default handler for a type.
status_t	GetTypeAndIcon (String zFile, Point cIconSize, String *zTypeName, Image **pcIcon, Message *pcMessage=NULL)
	Returns a description and an image for a file.
status_t	Launch (Window *pcParentWindow, String zFile, bool bVerbose=false, String zTitle="Select handler", bool bDefaultHandler=true)
	Launches a file.
void	UpdateAppList (bool bForce=false)
	Update the application list.
RegistrarAppList	GetAppList ()
	Returns the application list.
Static Public Member Functions
static RegistrarManager *	Get ()
	Provides access to the RegistrarManager class.
Classes
class	Private

---

Detailed Description

Description:

The RegistrarManager class provides a way to access the registrar, a server which manages the known filetypes. It is especially useful for applications to register the filetypes that they can handle. It can also be used to get the filetype and icon for files or to launch files with their associated application.

An example to register the current application as a handler for jpeg images:

 ...
 #include <atheos/image.h>
 #include <storage/registrar.h>

 MyApp::MyApp() : os::Application( "application/x-vnd-MyApp" )
 {
  try
  {
   os::RegistrarManager* pcManager = os::RegistrarManager::Get();
         pcManager->RegisterType( "image/x-jpg", "JPEG image" );
   pcManager->RegisterAsTypeHandler( "image/x-jpg" );
   // Assumes that you added the filetype icon as a resource
   pcManager->RegisterTypeIconFromRes( "image/x-jpg", "image_jpg.png" );
   pcManager->Put();
  }
 }

Author:

Arno Klenke ([email protected])

---

Constructor & Destructor Documentation

RegistrarManager::RegistrarManager

(

)

Should never be called! Use the Get() method instead.

Description:

Constructor. Should never be called! Use the Get() method instead.

Author:

Arno Klenke ([email protected])

RegistrarManager::~RegistrarManager

(

)

Never delete a RegistrarManager object! Use the Put() method instead.

Description:

Destructor. Never delete a RegistrarManager object! Use the Put() method instead.

Author:

Arno Klenke ([email protected])

---

Member Function Documentation

void RegistrarManager::AddRef

(

)

RegistrarManager * RegistrarManager::Get

(

)

[static]

Description:

Creates a new registrar manager if it does not exist. Otherwise return a pointer to the current one.

Note:

Make sure you call Put() afterwards. If the creation fails, an exception will be thrown.

See also:

Put()

Author:

Arno Klenke ([email protected])

void RegistrarManager::Put

(

bool

bAll = false

)

Description:

Decrements the reference counter of the instance.

Note:

Make sure that you do one call to this method for every Get() call in your appliction.

See also:

Get()

Author:

Arno Klenke ([email protected])

void RegistrarManager::HandleMessage

(

Message *

pcMessage

)

[virtual]

Description:

Overload this member to dispatch messages sendt to this handler. When a looper receives a message for one of it's handlers it will call the taget handlers HandleMessage() to allow the handler to dispatch the message.

The message passed in pcMessage is also available through os::Looper::GetCurrentMessage() and os::Looper::DetachCurrentMessage() until this member returns. This is normally not very usefull for HandleMessage() itself but it can be convinient for other members called from HandleMessage() in case they need data from the message that was not passed on from HandleMessage().

The looper will be locked when this member is called. The default implementation of this member will pass the message on to the next handler if one was set with SetNextHandler().

Note:

Never do any lenthy operations in any hook members that are called from the looper thread if the looper is involved with the GUI (for example if the looper is a os::Window). The looper will not be able to dispatch messages until the hook returns so spending a long time in this members will make the GUI feel unresponsive.

Parameters:

pcMessage

The message that should be handled. This message will be deleted by the looper when HandleMessage() returns unless you detach it with os::Looper::DetachCurrentMessage(),

See also:

os::Looper::DispatchMessage(), os::Looper::DetachCurrentMessage()

Author:

Kurt Skauen ([email protected])

Reimplemented from os::Handler.

void RegistrarManager::SetSynchronousMode

(

bool

bSync

)

Description:

Sets whether the registrar manager class is in synchronous mode. If this mode is activated, then all methods of this class will wait until the registrar server has updated its database.

Note:

The default value is false. This is ok in 99% of all cases.

Author:

Arno Klenke ([email protected])

status_t RegistrarManager::RegisterType	(	String	zMimeType,
		String	zIdentifier,
		bool	bOverwrite = false
	)

Description:

Registers a new filetype.

Parameters:

	zMimeType	- Mimetype of the new type.
	zIdentifier	- Name of the type.
	bOverwrite	- Whether the name should be overwritten if a type with the same mimetype already exists. false is almost always right.

Returns:

0 if the call was successful.

Author:

Arno Klenke ([email protected])

status_t RegistrarManager::UnregisterType

(

String

zMimeType

)

Description:

Unregisters a filetype.

Parameters:

zMimeType

- Mimetype of the type.

Returns:

0 if the call was successful.

Author:

Arno Klenke ([email protected])

status_t RegistrarManager::RegisterTypeIcon	(	String	zMimeType,
		Path	cIcon,
		bool	bOverwrite = false
	)

Description:

Sets a new icon for a filetype.

Parameters:

	zMimeType	- Mimetype of the type.
	zIcon	- Path to the new icon. The icon should be in /system/icons/filetypes/.
	bOverwrite	- Whether the icon should be overwritten if a type with the same mimetype already exists. false is almost always right.

Returns:

0 if the call was successful.

See also:

RegisterTypeIconFromRes()

Author:

Arno Klenke ([email protected])

status_t RegistrarManager::RegisterTypeIconFromRes	(	String	zMimeType,
		String	zIconRes,
		bool	bOverwrite = false
	)

Description:

Sets a new icon for a filetype. The icon will be extracted from the application resources.

Parameters:

	zMimeType	- Mimetype of the type.
	zIconRes	- Resource name of the icon.
	bOverwrite	- Whether the icon should be overwritten if a type with the same mimetype already exists. false is almost always right.

Returns:

0 if the call was successful.

See also:

RegisterTypeIcon()

Author:

Arno Klenke ([email protected])

status_t RegistrarManager::RegisterTypeExtension	(	String	zMimeType,
		String	zExtension
	)

Description:

Registers a new extension for a type. This is especially important for files on non native Syllable partitions.

Parameters:

	zMimeType	- Mimetype of the type.
	zExtension	- Extension that should be registeread.

Returns:

0 if the call was successful.

Author:

Arno Klenke ([email protected])

status_t RegistrarManager::ClearTypeExtensions

(

String

zMimeType

)

Description:

Clears the extension list for a type. Not often needed.

Parameters:

zMimeType

- Mimetype of the type.

Returns:

0 if the call was successful.

Author:

Arno Klenke ([email protected])

status_t RegistrarManager::RegisterTypeHandler	(	String	zMimeType,
		Path	cHandler
	)

Description:

Registers a new handler for a type.

Note:

If this is the first handler that is registered for the type then it will become the default handler.

Parameters:

	zMimeType	- Mimetype of the type.
	cHandler	- Absolute path to the handler.

Returns:

0 if the call was successful.

See also:

RegisterAsTypeHandler()

Author:

Arno Klenke ([email protected])

status_t RegistrarManager::RegisterAsTypeHandler

(

String

zMimeType

)

Description:

Registers the current application as a handler for a type.

Parameters:

zMimeType

- Mimetype of the type.

Returns:

0 if the call was successful.

See also:

RegisteTypeHandler()

Author:

Arno Klenke ([email protected])

status_t RegistrarManager::ClearTypeHandlers

(

String

zMimeType

)

Description:

Clears the handler list for a type. Not often needed.

Parameters:

zMimeType

- Mimetype of the type.

Returns:

0 if the call was successful.

Author:

Arno Klenke ([email protected])

int32 RegistrarManager::GetTypeCount

(

)

Description:

Returns the number of types that are registered for the calling user.

Returns:

The number of types.

Author:

Arno Klenke ([email protected])

RegistrarFileType RegistrarManager::GetType

(

int32

nIndex

)

Description:

Returns a RegistrarFileType object that describes a specific type.

Parameters:

nIndex

- Index of the type.

Returns:

The data.

See also:

GetTypeAndIcon()

Author:

Arno Klenke ([email protected])

status_t RegistrarManager::SetDefaultHandler	(	String	zMimeType,
		Path	zHandler
	)

Description:

Sets the default handler for a type. Make sure the handler is already registered.

Parameters:

	zMimeType	- Mimetype of the type.
	zHandler	- Absoulte path to the handler.

Returns:

0 if successful.

See also:

RegisterTypeHandler()

Author:

Arno Klenke ([email protected])

status_t RegistrarManager::GetTypeAndIcon	(	String	zFile,
		Point	cIconSize,
		String *	zTypeName,
		Image **	pcIcon,
		Message *	pcMessage = NULL
	)

Description:

Returns a description and an image for a file.

Parameters:

	zFile	- Path to the file.
	cIconSize	- Requested size of the icon.
	zTypeName	- Contains the type description after the call.
	pcIcon	- Contains the icon after the call.
	pcMessage	- Contains the full description of the type. In the same format as the returned message by GetType().

Returns:

0 if successful.

Author:

Arno Klenke ([email protected])

status_t RegistrarManager::Launch	(	Window *	pcParentWindow,
		String	zFile,
		bool	bVerbose = false,
		os::String	zTitle = "Select handler",
		bool	bDefaultHandler = true
	)

Description:

Launches a file. Executables will be started and other files will be run with their associated application. In verbose mode a dialog is presented to the user that lets him select the right filetype if no default handler is present.

Parameters:

	pcParentWindow	- Parent window. Can be NULL. The handler selector will be centered in this window.
	zFile	- Absolute path to the file.
	bVerbose	- Activates verbose mode.
	zTitle	- Title of the handler selector.
	bDefaultHandler	- If set to false, the handler selector will always be shown.

Returns:

0 if successful.

Author:

Arno Klenke ([email protected])

void RegistrarManager::UpdateAppList

(

bool

bForce = false

)

Description:

The registrar manages a list of installed applications in the /Applications folder. Using this method you can tell it to update this list.

Parameters:

bForce

- Force the registrar to update the list.

Author:

Arno Klenke ([email protected])

RegistrarAppList RegistrarManager::GetAppList

(

)

Description:

Returns the list of applications in /Applications.

Returns:

The application list.

Author:

Arno Klenke ([email protected])

---