💾 Archived View for lofi.haiku-os.org › docs › develop › servers › registrar › Protocols.gmi captured on 2023-12-28 at 15:24:53. Gemini links have been rewritten to link to archived content

-=-=-=-=-=-=-

Registrar Protocols

Standard Replies

standard success reply message

reply: B_REG_SUCCESS

[ <additional fields> ]

fields:

<additional fields>: Request-specific fields.

standard error reply message

reply: B_REG_ERROR

“error”: B_INT32_TYPE

[ “error_description”: B_STRING_TYPE ]

[ <additional fields> ]

fields:

“error”: The error code (a status_t).

“error_description”: Optional human readable description.

<additional fields>: Request-specific fields.

standard general result reply message

reply: B_REG_RESULT

“result”: B_INT32_TYPE

[ “result_description”: B_STRING_TYPE ]

[ <additional fields> ]

fields:

“result”: The result value (a status_t).

“result_description”: Optional human readable description.

<additional fields>: Request-specific fields.

General Requests

Getting the messengers

for MIME, clipboard and disk device management respectively

* * * * *

+----------------+---------------------------------------------------------+
| target         | registrar app looper (preferred handler)                |
+----------------+---------------------------------------------------------+
| message        | B_REG_GET_MIME_MESSENGERB_REG_GET_CLIPBOARD_MESSENGERB  |
|                | _REG_GET_DISK_DEVICE_MESSENGER                          |
+----------------+---------------------------------------------------------+
| reply          | standard success“messenger”: B_MESSENGER_TYPE           |
+----------------+---------------------------------------------------------+
| on error       | B_NO_REPLY (fatal)standard error (fatal)                |
+----------------+---------------------------------------------------------+

reply fields:

“messenger”: The requested messenger.

Shut down

* * * *

+----------------+---------------------------------------------------------+
| target         | registrar app looper (preferred handler)                |
+----------------+---------------------------------------------------------+
| message        | B_REG_SHUT_DOWN“reboot”:                                |
|                | B_BOOL_TYPE“confirm”:                                   |
|                | B_BOOL_TYPE“synchronously”:     B_BOOL_TYPE             |
+----------------+---------------------------------------------------------+
| reply          | standard success                                        |
+----------------+---------------------------------------------------------+
| on error       | B_NO_REPLY (fatal)standard error (fatal)                |
+----------------+---------------------------------------------------------+

message fields:

“reboot”: If true, the system reboots instead of turning the power off.

“confirm”: If true, the user will be asked to confirm to shut down the system.

“synchronously”: If true, the request sender gets a reply only, if the shutdown process fails. Otherwise the reply will be sent right before asking the user for confirmation (if desired).

Roster Requests

App registration (BRoster::AddApplication())

* * * * * * * * * *

+----------------+---------------------------------------------------------+
| target         | roster                                                  |
+----------------+---------------------------------------------------------+
| message        | B_REG_ADD_APP“signature”:                               |
|                | B_MIME_STRING_TYPE“ref”:                                |
|                | B_REF_TYPE“flags”:                                      |
|                | B_UINT32_TYPE“team”:                                    |
|                | B_INT32_TYPE“thread”:                                   |
|                | B_INT32_TYPE“port”:                                     |
|                | B_INT32_TYPE“full_registration”:         B_BOOL_TYPE    |
+----------------+---------------------------------------------------------+
| reply          | standard success[ “token”:                              |
|                | B_INT32_TYPE ][ “other_team”:                           |
|                | B_INT32_TYPE ]                                          |
+----------------+---------------------------------------------------------+
| on error       | B_NO_REPLY (fatal)standard error                        |
+----------------+---------------------------------------------------------+

message fields:

“signature”: The application signature.

“ref”: An entry_ref to the application executable.

“flags”: The application flags.

“team”: The application team (team_id).

“port”: The app looper port (port_id).

“full_registration”: Whether full or pre-registration is requested.

reply fields:

“token”: If pre-registration was requested (uint32). Unique token to be passed to BRoster::SetThreadAndTeam().

“other_team”: For single/exclusive launch applications that are launched the second time. The team ID of the already running instance (team_id).

error reply fields:

“error”:

B_BAD_VALUE: A request message field is missing or contains an invalid value.

B_ENTRY_NOT_FOUND: The entry_ref doesn’t refer to a file.

B_ALREADY_RUNNING: For single/exclusive launch applications that are launched the second time.

B_REG_ALREADY_REGISTERED: The team is already registered.

app registration (BRoster::CompleteRegistration())

* * * *

+----------------+---------------------------------------------------------+
| target         | roster                                                  |
+----------------+---------------------------------------------------------+
| message        | B_REG_COMPLETE_REGISTRATION“team”:                      |
|                | B_INT32_TYPE“thread”:    B_INT32_TYPE“port”:            |
|                | B_INT32_TYPE                                            |
+----------------+---------------------------------------------------------+
| reply          | standard success                                        |
+----------------+---------------------------------------------------------+
| on error       | B_NO_REPLY (fatal)standard error                        |
+----------------+---------------------------------------------------------+

message fields:

“team”: The application team (team_id).

“thread”: The application looper thread (thread_id).

“port”: The app looper port (port_id).

error reply fields:

“error”:

B_BAD_VALUE: A request message field is missing or contains an invalid value.

B_REG_APP_NOT_PRE_REGISTERED: The team is unknown to the roster or the application is already fully registered.

app registration check (BRoster::IsAppRegistered())

* * * * * *

+----------------+---------------------------------------------------------+
| target         | roster                                                  |
+----------------+---------------------------------------------------------+
| message        | B_REG_IS_APP_REGISTERED“ref”:               B_REF_TYPE( |
|                | “team”:    B_INT32_TYPE | “token”: B_INT32_TYPE )       |
+----------------+---------------------------------------------------------+
| reply          | standard success“registered”:                           |
|                | B_BOOL_TYPE“pre-registered”:    B_BOOL_TYPE[            |
|                | “app_info”:                flattened app_info ]         |
+----------------+---------------------------------------------------------+
| on error       | B_NO_REPLY (fatal)standard error                        |
+----------------+---------------------------------------------------------+

message fields:

“ref”: An entry_ref to the application executable.

“team”: The application team (team_id).

“token”: The application’s preregistration token.

reply fields:

“registered”: true, if the app is (pre-)registered, false otherwise.

“pre-registered”: true, if the app is pre-registered, false otherwise.

“app_info”: Flattened app info, if the app is known (i.e. (pre-)registered).

error reply fields:

“error”:

B_BAD_VALUE: A request message field is missing or contains an invalid value.

B_ENTRY_NOT_FOUND: The entry_ref doesn’t refer to a file.

pre-registrated app unregistration (BRoster::RemovePreRegApp())

+----------------+---------------------------------------------------------+
| target         | roster                                                  |
+----------------+---------------------------------------------------------+
| message        | B_REG_REMOVE_PRE_REGISTERED_APP“token”:                 |
|                | B_INT32_TYPE                                            |
+----------------+---------------------------------------------------------+
| reply          | standard success                                        |
+----------------+---------------------------------------------------------+
| on error       | B_NO_REPLY (fatal)standard error                        |
+----------------+---------------------------------------------------------+

message fields:

“token”: The token BRoster::AddApplication() returned (uint32).

error reply fields:

“error”:

B_BAD_VALUE: A request message field is missing or contains an invalid value.

B_REG_APP_NOT_PRE_REGISTERED: The token does not identify a pre-registered application.

app unregistration (BRoster::RemoveApp())

+----------------+---------------------------------------------------------+
| target         | roster                                                  |
+----------------+---------------------------------------------------------+
| message        | B_REG_REMOVE_APP“team”:      B_INT32_TYPE               |
+----------------+---------------------------------------------------------+
| reply          | standard success                                        |
+----------------+---------------------------------------------------------+
| on error       | B_NO_REPLY (fatal)standard error                        |
+----------------+---------------------------------------------------------+

message fields:

“team”: The application team (team_id).

error reply fields:

“error”:

B_BAD_VALUE: A request message field is missing or contains an invalid value.

B_REG_APP_NOT_REGISTERED: The team is unknown to the roster.

app pre-registration, set thread/team (BRoster::SetThreadAndTeam())

* * * *

+----------------+---------------------------------------------------------+
| target         | roster                                                  |
+----------------+---------------------------------------------------------+
| message        | B_REG_SET_THREAD_AND_TEAM“token”:                       |
|                | B_INT32_TYPE“team”:              B_INT32_TYPE“thread”:  |
|                | B_INT32_TYPE                                            |
+----------------+---------------------------------------------------------+
| reply          | standard success                                        |
+----------------+---------------------------------------------------------+
| on error       | B_NO_REPLY (fatal)standard error                        |
+----------------+---------------------------------------------------------+

message fields:

“token”: The token BRoster::AddApplication() returned (uint32).

“team”: The application team (team_id).

“thread”: The application looper thread (thread_id).

error reply fields:

“error”:

B_BAD_VALUE: A request message field is missing or contains an invalid value.

B_REG_APP_NOT_PRE_REGISTERED: The token does not identify a pre-registered application.

app registration, change app signature (BRoster::SetSignature())

* * *

+----------------+---------------------------------------------------------+
| target         | roster                                                  |
+----------------+---------------------------------------------------------+
| message        | B_REG_SET_SIGNATURE“team”:                              |
|                | B_INT32_TYPE“signature”: B_STRING_TYPE                  |
+----------------+---------------------------------------------------------+
| reply          | standard success                                        |
+----------------+---------------------------------------------------------+
| on error       | B_NO_REPLY (fatal)standard error                        |
+----------------+---------------------------------------------------------+

message fields:

“team”: The application team (team_id).

“signature”: The application’s new signature.

error reply fields:

“error”:

B_BAD_VALUE: A request message field is missing or contains an invalid value.

B_REG_APP_NOT_REGISTERED: The team does not identify a registered application.

get an app info (BRoster::Get{Running,Active,}AppInfo())

+----------------+---------------------------------------------------------+
| target         | roster                                                  |
+----------------+---------------------------------------------------------+
| message        | B_REG_GET_APP_INFO[ “team”:                             |
|                | B_INT32_TYPE“ref”:                                      |
|                | B_REF_TYPE“signature”:        B_STRING_TYPE ]           |
+----------------+---------------------------------------------------------+
| reply          | standard success“app_info”:  B_REG_APP_INFO_TYPE        |
+----------------+---------------------------------------------------------+
| on error       | B_NO_REPLY (fatal)standard error                        |
+----------------+---------------------------------------------------------+

message fields:

“team”: The application team (team_id).

“ref”: An entry_ref to the application executable.

“signature”: The application signature.

If both are omitted the active application is referred to.

reply fields:

“app_info”: The requested app_info (flat_app_info).

error reply fields:

“error”:

B_BAD_VALUE: A request message field is missing or contains an invalid value.

B_BAD_TEAM_ID: The supplied team ID does not identify a registered application.

B_ERROR:

An entry_ref or a signature has been supplied and no such application is currently running.

No team ID has been supplied and currently there is no active application.

get an app list (BRoster::GetAppList())

* * *

+----------------+---------------------------------------------------------+
| target         | roster                                                  |
+----------------+---------------------------------------------------------+
| message        | B_REG_GET_APP_LIST[ “signature”:       B_STRING_TYPE ]  |
+----------------+---------------------------------------------------------+
| reply          | standard success“teams”:     B_INT32_TYPE[]             |
+----------------+---------------------------------------------------------+
| on error       | B_NO_REPLY (fatal)standard error                        |
+----------------+---------------------------------------------------------+

message fields:

“signature”: The application signature.

reply fields:

“teams”: The requested list of team IDs (team_id).

error reply fields:

“error”:

B_BAD_VALUE: A request message field is missing or contains an invalid value.

activate an app (BRoster::ActivateApp())

+----------------+---------------------------------------------------------+
| target         | roster                                                  |
+----------------+---------------------------------------------------------+
| message        | B_REG_ACTIVATE_APP“team”:        B_INT32_TYPE           |
+----------------+---------------------------------------------------------+
| reply          | standard success                                        |
+----------------+---------------------------------------------------------+
| on error       | B_NO_REPLY (fatal)standard error                        |
+----------------+---------------------------------------------------------+

message fields:

“team”: The application team (team_id).

error reply fields:

“error”:

B_BAD_VALUE: A request message field is missing or contains an invalid value.

B_BAD_TEAM_ID: The supplied team ID does not identify a registered application.

broadcast a message (BRoster::Broadcast())

* * * *

+----------------+---------------------------------------------------------+
| target         | roster                                                  |
+----------------+---------------------------------------------------------+
| message        | B_REG_BROADCAST“team”:                                  |
|                | B_INT32_TYPE“message”:                                  |
|                | B_MESSAGE_TYPE“reply_target”:      B_MESSENGER_TYPE     |
+----------------+---------------------------------------------------------+
| reply          | standard success                                        |
+----------------+---------------------------------------------------------+
| on error       | B_NO_REPLY (fatal)standard error                        |
+----------------+---------------------------------------------------------+

message fields:

“team”: The requesting team (team_id).

“message”: The message to be broadcast.

“reply_target”: The reply target for the message.

error reply fields:

“error”:

B_BAD_VALUE: A request message field is missing or contains an invalid value.

start roster watching (BRoster::StartWatching())

* * *

+----------------+---------------------------------------------------------+
| target         | roster                                                  |
+----------------+---------------------------------------------------------+
| message        | B_REG_START_WATCHING“target”:                           |
|                | B_MESSENGER_TYPE“events”:    B_INT32_TYPE               |
+----------------+---------------------------------------------------------+
| reply          | standard success                                        |
+----------------+---------------------------------------------------------+
| on error       | B_NO_REPLY (fatal)standard error                        |
+----------------+---------------------------------------------------------+

message fields:

“target”: The target the event messages shall be sent to.

“events”: Specifies the events the caller is interested in (uint32).

error reply fields:

“error”:

B_BAD_VALUE: A request message field is missing or contains an invalid value.

stop roster watching (BRoster::StopWatching())

+----------------+---------------------------------------------------------+
| target         | roster                                                  |
+----------------+---------------------------------------------------------+
| message        | B_REG_STOP_WATCHING“target”:    B_MESSENGER_TYPE        |
+----------------+---------------------------------------------------------+
| reply          | standard success                                        |
+----------------+---------------------------------------------------------+
| on error       | B_NO_REPLY (fatal)standard error                        |
+----------------+---------------------------------------------------------+

message fields:

“target”: The target that shall not longer receive any event messages.

error reply fields:

“error”:

B_BAD_VALUE: A request message field is missing or contains an invalid value.

MIME Database Requests

install a mime type (BMimeType::Install())

+----------------+---------------------------------------------------------+
| target         | mime manager (BRoster::fMimeMess)                       |
+----------------+---------------------------------------------------------+
| message        | B_REG_MIME_INSTALL“type”: B_STRING_TYPE                 |
+----------------+---------------------------------------------------------+
| reply          | standard general result                                 |
+----------------+---------------------------------------------------------+

message fields:

“type”: The mime type

reply fields:

“result”:

B_OK: success

B_FILE_EXISTS: the type is already installed

remove a mime type (BMimeType::Delete())

+----------------+---------------------------------------------------------+
| target         | mime manager (BRoster::fMimeMess)                       |
+----------------+---------------------------------------------------------+
| message        | B_REG_MIME_DELETE“type”: B_STRING_TYPE                  |
+----------------+---------------------------------------------------------+
| reply          | standard general result                                 |
+----------------+---------------------------------------------------------+

message fields:

“type”: The mime type

reply fields:

“result”:

B_OK: success

B_ENTRY_NOT_FOUND: the type was not found

(other error code): failure

set a specific attribute of a mime type (BMimeType::Set*()), installing if necessary

+----------------+---------------------------------------------------------+
| target         | mime manager (BRoster::fMimeMess)                       |
+----------------+---------------------------------------------------------+
| message        | B_REG_MIME_SET_PARAM“type”: B_STRING_TYPE“which”:       |
|                | B_INT32_TYPE[ additional fields depending upon the      |
|                | “which” field (see below) ]                             |
+----------------+---------------------------------------------------------+
| reply          | standard general result                                 |
+----------------+---------------------------------------------------------+

message fields:

“type”: The mime type

“which”: Which attribute to set. May be one of the following:

+-----------------------------+---------------------------------+-------------------------------------+
| “which”                     | additional message fields       | field comments                      |
|=============================|=================================|=====================================|
| B_REG_MIME_ICON             | “icon data”: B_RAW_TYPE,        | B_CMAP8 bitmap data only            |
|                             +---------------------------------+-------------------------------------+
|                             | “icon size”: B_INT32_TYPE       | B_{MINI,LARGE}_ICON or -1 for flat  |
|                             |                                 | vector icon data                    |
+-----------------------------+---------------------------------+-------------------------------------+
| B_REG_MIME_PREFERRED_APP    | “signature”: B_STRING_TYPE      |                                     |
|                             +---------------------------------+-------------------------------------+
|                             | “app verb”: B_INT32_TYPE        |                                     |
+-----------------------------+---------------------------------+-------------------------------------+
| B_REG_MIME_ATTR_INFO        | “attr info”: B_MESSAGE_TYPE     |                                     |
+-----------------------------+---------------------------------+-------------------------------------+
| B_REG_MIME_FILE_EXTENSIONS  | “extensions”: B_MESSAGE_TYPE    |                                     |
+-----------------------------+---------------------------------+-------------------------------------+
| B_REG_MIME_DESCRIPTION      | “long”: B_BOOL_TYPE,            |                                     |
|                             +---------------------------------+-------------------------------------+
|                             | “description”: B_STRING_TYPE    |                                     |
+-----------------------------+---------------------------------+-------------------------------------+
| B_REG_MIME_SNIFFER_RULE     | “sniffer rule”: B_STRING_TYPE   |                                     |
+-----------------------------+---------------------------------+-------------------------------------+
| B_REG_MIME_APP_HINT         | “app hint”: B_REF_TYPE          |                                     |
+-----------------------------+---------------------------------+-------------------------------------+
| B_REG_MIME_ICON_FOR_TYPE    | “file type”: B_STRING_TYPE,     |                                     |
|                             +---------------------------------+-------------------------------------+
|                             | “icon data”: B_RAW_TYPE,        |                                     |
|                             +---------------------------------+-------------------------------------+
|                             | “icon size”: B_INT32_TYPE       |                                     |
+-----------------------------+---------------------------------+-------------------------------------+
| B_REG_MIME_SUPPORTED_TYPES  | “types”: B_MESSAGE_TYPE         |                                     |
+-----------------------------+---------------------------------+-------------------------------------+

reply fields:

“result”:

B_OK: success

(error code): failure

delete a specific attribute of a mime type (BMimeType::Delete*()),

+----------------+---------------------------------------------------------+
| target         | mime manager (BRoster::fMimeMess)                       |
+----------------+---------------------------------------------------------+
| message        | B_REG_MIME_DELETE_PARAM“type”: B_STRING_TYPE“which”:    |
|                | B_INT32_TYPE[ additional fields depending upon the      |
|                | “which” field (see below) ]                             |
+----------------+---------------------------------------------------------+
| reply          | standard general result                                 |
+----------------+---------------------------------------------------------+

message fields:

“type”: The mime type

“which”: Which attribute to delete. May be one of the following:

+-----------------------------+---------------------------------+-------------------------------------+
| “which”                     | additional message fields       | field comments                      |
|=============================|=================================|=====================================|
| B_REG_MIME_ICON:            | “icon size”: B_INT32_TYPE       | B_{MINI,LARGE}_ICON or -1 for       |
|                             |                                 | vector icon data                    |
+-----------------------------+---------------------------------+-------------------------------------+
| B_REG_MIME_PREFERRED_APP    | “app verb”: B_INT32_TYPE        |                                     |
+-----------------------------+---------------------------------+-------------------------------------+
| B_REG_MIME_ATTR_INFO        |                                 |                                     |
+-----------------------------+---------------------------------+-------------------------------------+
| B_REG_MIME_FILE_EXTENSIONS  |                                 |                                     |
+-----------------------------+---------------------------------+-------------------------------------+
| B_REG_MIME_DESCRIPTION      | “long”: B_BOOL_TYPE             |                                     |
+-----------------------------+---------------------------------+-------------------------------------+
| B_REG_MIME_SNIFFER_RULE     |                                 |                                     |
+-----------------------------+---------------------------------+-------------------------------------+
| B_REG_MIME_APP_HINT         |                                 |                                     |
+-----------------------------+---------------------------------+-------------------------------------+
| B_REG_MIME_ICON_FOR_TYPE    | “file type”: B_STRING_TYPE,     |                                     |
|                             +---------------------------------+-------------------------------------+
|                             | “icon size”: B_INT32_TYPE       |                                     |
+-----------------------------+---------------------------------+-------------------------------------+
| B_REG_MIME_SUPPORTED_TYPES  |                                 |                                     |
+-----------------------------+---------------------------------+-------------------------------------+

reply fields:

“result”:

B_OK: success

B_ENTRY_NOT_FOUND: no such attribute exists, or the type is not installed

(other error code): failure

subscribe a BMessenger to the MIME monitor service (BMimeType::StartWatching())

+----------------+---------------------------------------------------------+
| target         | mime manager (BRoster::fMimeMess)                       |
+----------------+---------------------------------------------------------+
| message        | B_REG_MIME_START_WATCHING“target”: B_MESSENGER_TYPE     |
+----------------+---------------------------------------------------------+
| reply          | standard general result                                 |
+----------------+---------------------------------------------------------+

message fields:

“target”: The BMessenger subscribing to the monitor service

reply fields:

“result”:

B_OK: success

(error code): failure

unsubscribe a BMessenger from the MIME monitor service (BMimeType::StopWatching())

+----------------+---------------------------------------------------------+
| target         | mime manager (BRoster::fMimeMess)                       |
+----------------+---------------------------------------------------------+
| message        | B_REG_MIME_STOP_WATCHING“target”: B_MESSENGER_TYPE      |
+----------------+---------------------------------------------------------+
| reply          | standard general result                                 |
+----------------+---------------------------------------------------------+

message fields:

“target”: The BMessenger unsubscribing from the monitor service

reply fields:

“result”:

B_OK: success

B_ENTRY_NOT_FOUND: the given BMessenger was not subscribed to the service

(other error code): failure

perform an update_mime_info() call

* * *

+----------------+---------------------------------------------------------+
| target         | mime manager (BRoster::fMimeMess)                       |
+----------------+---------------------------------------------------------+
| message        | B_REG_MIME_UPDATE_MIME_INFO“entry”:                     |
|                | B_REF_TYPE“recursive”: B_BOOLEAN_TYPE“synchronous”:     |
|                | B_BOOLEAN_TYPE“force”: B_INT32_TYPE                     |
+----------------+---------------------------------------------------------+
| reply          | standard general result                                 |
+----------------+---------------------------------------------------------+

message fields:

“entry”: The base entry to update.

“recursive”: If true and “entry” is a directory, update all entries below “entry” in the hierarchy.

“synchronous”: If true, the call will block until the operation is completed. If false, the call will return immediately and the operation will run asynchronously in another thread.

“force”: Specifies how to handle entries for which a BEOS:TYPE attribute already exists. Valid values are B_UPDATE_MIME_INFO_{NO_FORCE, FORCE_KEEP_TYPE, FORCE_UPDATE_ALL}.

reply fields:

“result”:

B_OK: The asynchronous update_mime_info() call has been successfullystarted (and may still be running).

(error code): failure

perform a create_app_meta_mime() call

* * *

+----------------+---------------------------------------------------------+
| target         | mime manager (BRoster::fMimeMess)                       |
+----------------+---------------------------------------------------------+
| message        | B_REG_MIME_CREATE_APP_META_MIME“entry”:                 |
|                | B_REF_TYPE“recursive”: B_BOOLEAN_TYPE“synchronous”:     |
|                | B_BOOLEAN_TYPE“force”: B_INT32_TYPE                     |
+----------------+---------------------------------------------------------+
| reply          | standard general result                                 |
+----------------+---------------------------------------------------------+

message fields:

“entry”: The base entry to update.

“recursive”: If true and “entry” is a directory, update all entries below “entry” in the hierarchy.

“synchronous”: If true, the call will block until the operation is completed. If false, the call will return immediately and the operation will run asynchronously in another thread.

“force”: If != 0, also update entries for which meta app information already exists.

reply fields:

“result”:

B_OK: The asynchronous update_mime_info() call has been successfullystarted (and may still be running).

(error code): failure

notify the thread manager to perform a clean up run

+----------------+-------------------------------------------------------------------------------+
| target         | thread manager/mime manager (MIMEManager::fThreadManager/BRoster::fMimeMess)  |
+----------------+-------------------------------------------------------------------------------+
| message        | B_REG_MIME_UPDATE_THREAD_FINISHED                                             |
+----------------+-------------------------------------------------------------------------------+
| reply          | none (message should be sent asynchronously)                                  |
+----------------+-------------------------------------------------------------------------------+

Message Runner Requests

message runner registration (BMessageRunner::InitData())

* * * * * * * *

+----------------+---------------------------------------------------------+
| target         | roster                                                  |
+----------------+---------------------------------------------------------+
| message        | B_REG_REGISTER_MESSAGE_RUNNER“team”:                    |
|                | B_INT32_TYPE“target”:                                   |
|                | B_MESSENGER_TYPE“message”:                              |
|                | B_MESSAGE_TYPE“interval”:                               |
|                | B_INT64_TYPE“count”:                                    |
|                | B_INT32_TYPE“reply_target”:                             |
|                | B_MESSENGER_TYPE                                        |
+----------------+---------------------------------------------------------+
| reply          | standard success“token”:                                |
|                | B_INT32_TYPE                                            |
+----------------+---------------------------------------------------------+
| on error:      | B_NO_REPLY (fatal)standard error                        |
+----------------+---------------------------------------------------------+

message fields:

“team”: ID of the team owning the BMessageRunner (team_id).

“target”: The message target.

“message”: The message to be sent to the target.

“interval”: Period of time before the first message is sent and between messages (if more than one shall be sent) in microseconds.

“count”: Specifies how many times the message shall be sent. A value less than 0 for an unlimited number of repetitions.

“reply_target”: Target replies to the delivered message(s) shall be sent to.

reply fields:

“token”: Unique token identifying the message runner.

error reply fields:

“error”:

B_BAD_VALUE: A request message field is missing or contains an invalid value.

message runner unregistration (BMessageRunner::~BMessageRunner())

+----------------+---------------------------------------------------------+
| target         | roster                                                  |
+----------------+---------------------------------------------------------+
| message:       | B_REG_UNREGISTER_MESSAGE_RUNNER“token”:                 |
|                | B_INT32_TYPE                                            |
+----------------+---------------------------------------------------------+
| reply          | standard success                                        |
+----------------+---------------------------------------------------------+
| on error:      | B_NO_REPLY (fatal)standard error                        |
+----------------+---------------------------------------------------------+

message fields:

“token”: Unique token identifying the message runner. Returned by the B_REG_REGISTER_MESSAGE_RUNNER request.

error reply fields:

“error”:

B_BAD_VALUE: A request message field is missing or contains an invalid value.

set message runner parameters (BMessageRunner::SetParams())

* * * *

+----------------+---------------------------------------------------------+
| target         | roster                                                  |
+----------------+---------------------------------------------------------+
| message        | B_REG_SET_MESSAGE_RUNNER_PARAMS“token”:                 |
|                | B_INT32_TYPE[ “interval”:                               |
|                | B_INT64_TYPE ][ “count”:                                |
|                | B_INT32_TYPE ]                                          |
+----------------+---------------------------------------------------------+
| reply          | standard success                                        |
+----------------+---------------------------------------------------------+
| on error:      | B_NO_REPLY (fatal)standard error                        |
+----------------+---------------------------------------------------------+

message fields:

“token”: Unique token identifying the message runner. Returned by the B_REG_REGISTER_MESSAGE_RUNNER request.

“interval”: Period of time before the first message is sent and between messages (if more than one shall be sent) in microseconds.

“count”: Specifies how many times the message shall be sent. A value less than 0 for an unlimited number of repetitions.

error reply fields:

“error”:

B_BAD_VALUE: A request message field is missing or contains an invalid value.

get message runner info (BMessageRunner::InitData())

* * * *

+----------------+---------------------------------------------------------+
| target         | roster                                                  |
+----------------+---------------------------------------------------------+
| message:       | B_REG_GET_MESSAGE_RUNNER_INFO“token”:                   |
|                | B_INT32_TYPE                                            |
+----------------+---------------------------------------------------------+
| reply          | standard success“interval”:                             |
|                | B_INT64_TYPE“count”:                                    |
|                | B_INT32_TYPE                                            |
+----------------+---------------------------------------------------------+
| on error:      | B_NO_REPLY (fatal)standard error                        |
+----------------+---------------------------------------------------------+

message fields:

“token”: Unique token identifying the message runner. Returned by the B_REG_REGISTER_MESSAGE_RUNNER request.

reply fields:

“interval”: Period of time before the first message is sent and between messages (if more than one shall be sent) in microseconds.

“count”: Specifies how many times the message still has to be sent. A value less than 0 for an unlimited number of repetitions.

error reply fields:

“error”:

B_BAD_VALUE: A request message field is missing or contains an invalid value.

Clipboard Handler Requests

add new clipboard to system (BClipboard::BClipboard())

+----------------+---------------------------------------------------------+
| target         | clipboard handler                                       |
+----------------+---------------------------------------------------------+
| message        | B_REG_ADD_CLIPBOARD“name”:                              |
|                | B_STRING_TYPE                                           |
+----------------+---------------------------------------------------------+
| reply          | standard general result                                 |
+----------------+---------------------------------------------------------+

message fields:

“name”: Name used to identify the particular clipboard to add

reply fields:

“result”:

B_OK: success

B_BAD_VALUE: name field was not specified in message

get clipboard write count (BClipboard::GetSystemCount())

+----------------+---------------------------------------------------------+
| target         | clipboard handler                                       |
+----------------+---------------------------------------------------------+
| message        | B_REG_GET_CLIPBOARD_COUNT“name”:                        |
|                | B_STRING_TYPE                                           |
+----------------+---------------------------------------------------------+
| reply          | standard general result“count”:                         |
|                | B_INT32_TYPE                                            |
+----------------+---------------------------------------------------------+

message fields:

“name”: Name used to identify the particular clipboard

reply fields:

“result”:

B_OK: success

B_BAD_VALUE: no name / no valid name specified in message

“count”:

number of times this clipboard has been written to

start watching clipboard (BClipboard::StartWatching())

+----------------+---------------------------------------------------------+
| target         | clipboard handler                                       |
+----------------+---------------------------------------------------------+
| message        | B_REG_CLIPBOARD_START_WATCHING“name”:                   |
|                | B_STRING_TYPE“target”:                                  |
|                | B_MESSENGER_TYPE                                        |
+----------------+---------------------------------------------------------+
| reply          | standard general result                                 |
+----------------+---------------------------------------------------------+

message fields:

“name”: Name used to identify the particular clipboard

“target”: Messenger pointing to the target to notify

reply fields:

“result”:

B_OK: success

B_BAD_VALUE: no name / no valid name specified in messageno target specified

stop watching clipboard (BClipboard::StopWatching())

+----------------+---------------------------------------------------------+
| target         | clipboard handler                                       |
+----------------+---------------------------------------------------------+
| message        | B_REG_CLIPBOARD_STOP_WATCHING“name”:                    |
|                | B_STRING_TYPE“target”:                                  |
|                | B_MESSENGER_TYPE                                        |
+----------------+---------------------------------------------------------+
| reply          | standard general result                                 |
+----------------+---------------------------------------------------------+

message fields:

“name”: Name used to identify the particular clipboard

“target”: Messenger pointing to the target to remove from the notify list

reply fields:

“result”:

B_OK: success

B_BAD_VALUE: no name / no valid name specified in message / no target specified

download clipboard data (BClipboard::DownloadFromSystem())

+----------------+---------------------------------------------------------+
| target         | clipboard handler                                       |
+----------------+---------------------------------------------------------+
| message        | B_REG_DOWNLOAD_CLIPBOARD“name”:                         |
|                | B_STRING_TYPE                                           |
+----------------+---------------------------------------------------------+
| reply          | standard general result“data”:                          |
|                | B_MESSAGE_TYPE“data source”:                            |
|                | B_MESSENGER_TYPE“count”:                                |
|                | B_INT32_TYPE                                            |
+----------------+---------------------------------------------------------+

message fields:

“name”: Name used to identify the particular clipboard

reply fields:

“result”:

B_OK: success

B_BAD_VALUE: no name / no valid name specified in message no target specified

“data”: message with Data fields containing the contents of the clipboard

“data source”: messenger to the be_app_messenger of the application which last wrote data

“count”: number of times this clipboard has been written to

upload clipboard data (BClipboard::UploadToSystem())

+----------------+---------------------------------------------------------+
| target         | clipboard handler                                       |
+----------------+---------------------------------------------------------+
| message        | B_REG_UPLOAD_CLIPBOARD“name”:                           |
|                | B_STRING_TYPE “data”:                                   |
|                | B_MESSAGE_TYPE “data source”:                           |
|                | B_MESSENGER_TYPE                                        |
+----------------+---------------------------------------------------------+
| reply          | standard general result“count”:                         |
|                | B_INT32_TYPE                                            |
+----------------+---------------------------------------------------------+

message fields:

“name”: Name used to identify the particular clipboard

“data”: message with Data fields containing the contents of the clipboard

“data source”: messenger to the be_app_messenger of the application which last wrote data

reply fields:

“result”:

B_OK: success

B_BAD_VALUE: no name / no valid name specified in message / no target specified

“count”:

number of times this clipboard has been written to

Disk Device Requests

get next disk device

+----------------+---------------------------------------------------------+
| target         | disk device manager                                     |
+----------------+---------------------------------------------------------+
| message        | B_REG_NEXT_DISK_DEVICE“cookie”:                         |
|                | B_INT32_TYPE                                            |
+----------------+---------------------------------------------------------+
| reply          | standard general result“device”:                        |
|                | B_MESSAGE_TYPE“cookie”:                                 |
|                | B_INT32_TYPE                                            |
+----------------+---------------------------------------------------------+

message fields:

“cookie”: An iteration cookie. Initially 0.

reply fields:

“device”: Archived BDiskDevice info.

“cookie”: Next value for the iteration cookie.

“result”:

B_BAD_VALUE: A request message field is missing or contains an invalid value.

B_ENTRY_NOT_FOUND: Iteration finished.

get disk device

+----------------+---------------------------------------------------------+
| target         | disk device manager                                     |
+----------------+---------------------------------------------------------+
| message        | B_REG_GET_DISK_DEVICE“device_id”:                       |
|                | B_INT32_TYPE“session_id”:                               |
|                | B_INT32_TYPE“partition_id”:            B_INT32_TYPE     |
+----------------+---------------------------------------------------------+
| reply          | standard general result“device”:                        |
|                | B_MESSAGE_TYPE                                          |
+----------------+---------------------------------------------------------+

message fields:

“device_id”: ID of the device to be retrieved.

“session_id”: ID of session whose device shall be retrieved.

“partition_id”: ID of partition whose device shall be retrieved.

reply fields:

“device”: Archived BDiskDevice info.

“result”:

B_BAD_VALUE: A request message field is missing or contains an invalid value.

B_ENTRY_NOT_FOUND: A device/session/partition with that ID could notbe found.

update disk device

* * *

+----------------+---------------------------------------------------------+
| target         | disk device manager                                     |
+----------------+---------------------------------------------------------+
| message        | B_REG_UPDATE_DISK_DEVICE“device_id”:                    |
|                | B_INT32_TYPE“session_id”:                               |
|                | B_INT32_TYPE“partition_id”:                             |
|                | B_INT32_TYPE“change_counter”:                           |
|                | B_INT32_TYPE“update_policy”:             B_INT32_TYPE   |
+----------------+---------------------------------------------------------+
| reply          | standard general result“up_to_date”:                    |
|                | B_BOOLEAN_TYPE[ “device”:                               |
|                | B_MESSAGE_TYPE ]                                        |
+----------------+---------------------------------------------------------+

message fields:

“device_id”: ID of the device to be retrieved.

“session_id”: ID of session whose device shall be retrieved.

“partition_id”: ID of partition whose device shall be retrieved.

“change_counter”: Change counter of the object (or device in case of B_REG_DEVICE_UPDATE_DEVICE_CHANGED update policy) in question.

“update_policy”: (uint32)

B_REG_DEVICE_UPDATE_CHECK: Check only, if the object is up to date.

B_REG_DEVICE_UPDATE_CHANGED: Update only, if the object has changed.

B_REG_DEVICE_UPDATE_DEVICE_CHANGED: Update, if the device has changed, even if the partition/session has not.

The latter two have the same semantics, if the object is a device.

reply fields:

“up_to_date”: true, if the object (and for B_REG_DEVICE_UPDATE_DEVICE_CHANGED also the device) is already up to date, false otherwise.

“device”: Archived BDiskDevice info.

“result”:

B_BAD_VALUE: A request message field is missing or contains an invalid value.

B_ENTRY_NOT_FOUND: A device/session/partition with that ID could not be found.

start disk device watching

* * *

+----------------+---------------------------------------------------------+
| target         | disk device manager                                     |
+----------------+---------------------------------------------------------+
| message        | B_REG_DEVICE_START_WATCHING“target”:                    |
|                | B_MESSENGER_TYPE“events”:    B_INT32_TYPE               |
+----------------+---------------------------------------------------------+
| reply          | standard general result                                 |
+----------------+---------------------------------------------------------+
| on error       | B_NO_REPLY (fatal)standard error                        |
+----------------+---------------------------------------------------------+

message fields:

“target”: The target the event messages shall be sent to.

“events”: Specifies the events the caller is interested in (uint32).

“result”:

B_BAD_VALUE: A request message field is missing or contains an invalid value.

stop disk device watching

+----------------+---------------------------------------------------------+
| target         | disk device manager                                     |
+----------------+---------------------------------------------------------+
| message        | B_REG_DEVICE_STOP_WATCHING“target”:    B_MESSENGER_TYPE |
+----------------+---------------------------------------------------------+
| reply          | standard general result                                 |
+----------------+---------------------------------------------------------+
| on error       | B_NO_REPLY (fatal)standard error                        |
+----------------+---------------------------------------------------------+

message fields:

“target”: The target that shall not longer receive any event messages.

“result”:

B_BAD_VALUE: A request message field is missing or contains an invalid value.