//
// File:  if/locator.idl
//
// Description: Interface for name resolution
//

/* our datatypes & exceptions */
#include <types.idl>

const interfaceid_t ANY_INTERFACE         = 0xffffffff;
const interfaceid_t NO_INTERFACE          = 0;
const objectid_t    INVALID_OBJECT        = 0xffffffff;
const objectid_t    ROOT_DIRECTORY_HANDLE = 0;
const uint16_t      NAME_LENGTH           = 64;

/**
 * Querying interface, that allows picking named entries from directories.
 * Implemented by locator, fileserver and others.
 */
[uuid(IF_DIRECTORY_ID)]
interface IF_DIRECTORY {
	/** 
	 * Query the directory specified with @p directory_handle for an entry with
	 * name @p name, that supports interface @p interface. If you wanna query
	 * the toplevel directory then you can use ROOT_DIRECTORY_HANDLE. It
	 * returns a server that speaks this interface and an object handle for
	 * this server
	 */
	void GetEntry(in objectid_t directory_handle, in string name,
	              in interfaceid_t interfaceid,
	              out L4_ThreadId_t server, out objectid_t object_handle)
		raises(not_supported, not_found, invalid_objectid);
};

/**
 * Interface implemented by the locator, so that other operating system servers
 * can announce their services.
 */
[uuid(IF_NAMING_ID)]
interface IF_NAMING {
	/**
	 * Register the current server at the locator.
	 * The server gets registered with name @p name and interface
	 * @p interfaceid. You can register a server multiple times with different
	 * interfaces or names.
	 */
	void Register(in string name, in interfaceid_t interfaceid,
	              in objectid_t root_directory)
		raises(already_registered);
	/**
	 * Unregisters an existing @p name, @p interface entry. If no such entry
	 * exists nothing happens.
	 */
	void Unregister(in string name, in interfaceid_t interfaceid);
};

/**
 * Interface for querying a list of entries in a directory. May be implemented
 * by servers that implemented IF_DIRECTORY.
 */
[uuid(IF_ENUMERABLE_ID)]
interface IF_ENUMERABLE {
	/**
	 * Returns the nth entry of a directory. You can only query for entries
	 * with a specific interface or any interface by using the ANY_INTERFACE
	 * constant.
	 * The returned server is L4_nilthread if the entry doesn't exist.
	 */
	void EnumerateEntry(in objectid_t directory_handle, in interfaceid_t interfaceid,
	                    in L4_Word_t entry, out L4_ThreadId_t server, out objectid_t object_handle,
	                    out string name)
		raises(invalid_objectid);
};