mojo_service_manager/lib/mojom/service_manager.mojom

// Copyright 2022 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// API exposed by the ChromeOS mojo service manager.

// NOTE: This mojom should be kept in sync with the copy in Chromium's repo in
// src/chromeos/components/mojo_service_manager/mojom/mojo_service_manager.mojom

module chromeos.mojo_service_manager.mojom;

import "mojo_service_manager/lib/mojom/time.mojom";

// Manages services provided by processes running on the system.
// The argument |service_name| should match the regex ([a-zA-Z0-9._\-]+).
//
// Next MinVersion: 1
// Next Method ID: 4
interface ServiceManager {
  // Registers a service to the service manager. Callers should set disconnect
  // handler on another end of |service_provider| to handle errors.
  Register@0(string service_name,
             pending_remote<ServiceProvider> service_provider);

  // Requests a service from the service manager. The |receiver| will be bound
  // to the service. In the case that the service is not registered, if
  // |timeout| is null, the |receiver| will be bound after the service is
  // available. If |timeout| is not null and the |receiver| cannot be bound
  // after |timeout|, it will be reset. Callers should set disconnect handler on
  // another end of |receiver| to handle errors.
  Request@1(string service_name, mojo_base.mojom.TimeDelta? timeout,
            handle<message_pipe> receiver);

  // Queries the state of a service.
  Query@2(string service_name) => (ErrorOrServiceState result);

  // Registers an observer to observe the state of services. The observer can
  // only receive the events related to the services which the callers are
  // allowed to request. Callers should set disconnect handler on another end of
  // |observer| to handle errors.
  AddServiceObserver@3(pending_remote<ServiceObserver> observer);
};

// Provides services to other processes. Provider processes implement this and
// register it to the service manager.
//
// Next MinVersion: 1
// Next Method ID: 1
interface ServiceProvider {
  // Requests to bind the |receiver| to the corresponding mojo interface. The
  // |client_identity| can be used to identify the requester processes.
  // Note: the implementations can reset |receiver| to return errors. They
  // should use the error codes defined in |ErrorCode| enum when returning
  // errors.
  Request@0(ProcessIdentity client_identity,
            handle<message_pipe> receiver);
};

// Observes the service events. Requester processes implement this and register
// it to the service manager.
//
// Next MinVersion: 1
// Next Method ID: 1
interface ServiceObserver {
  // Is called when service events occur.
  OnServiceEvent@0(ServiceEvent event);
};

// The identity information about a process.
//
// Next MinVersion: 1
// Next Field ID: 4
struct ProcessIdentity {
  // The SELinux security context.
  string security_context@0;
  // The process id.
  uint32 pid@1;
  // The user / group id.
  uint32 uid@2;
  uint32 gid@3;
};

// The result of ServiceManager::Query.
//
// Next MinVersion: 1
union ErrorOrServiceState {
  // The result if succeeds.
  ServiceState state;
  // The error if fails.
  Error error;
};

// The state of a service.
//
// Next MinVersion: 1
// Next Field ID: 2
struct ServiceState {
  // The service is registered or not.
  bool is_registered@0;
  // The identity of the owner of the service. This is omitted if the service
  // is not registered.
  ProcessIdentity? owner@1;
};

// The event about a service.
//
// Next MinVersion: 1
// Next Field ID: 3
struct ServiceEvent {
  [Extensible]
  enum Type {
    // The default value for forward compatibility. All the unknown value will
    // be mapped to this.
    [Default] kUnknown,
    // The service is registered.
    kRegistered,
    // The service is not registered.
    kUnRegistered,
  };

  Type type@0;
  // The name of the service which triggers the event.
  string service_name@1;
  // The dispatcher of the event. It is the process which registered or
  // unregistered the service.
  ProcessIdentity dispatcher@2;
};

// A generic error type for functions to return error.
//
// Next MinVersion: 1
// Next Field ID: 2
struct Error {
  ErrorCode code@0;
  string message@1;
};

// The error code for |struct Error| and the disconnect handlers. This is used
// in the disconnect reason of all the mojo handles (namely, message pipe,
// receiver and remote) which are sent to |ServiceManager|.
// Note that in the disconnect handlers, this is casted to |uint32| and has no
// guarantee that the value can be casted back to this. Always check if the
// value is between 1 and |ErrorCode::kMaxValue| before casting it.
//
// NextMinVersion: 1
[Extensible]
enum ErrorCode {
  // The default value for forward compatibility. In struct |Error|, all the
  // unknown value will be mapped to this.
  // In disconnect handlers, if the handle is reset without a reason, the error
  // code is 0. So this enum starts from 1 to be distinguish from that.
  [Default] kUnknown = 1,
  // Timeout is reached.
  kTimeout,
  // The caller is not permit to perform the operation.
  kPermissionDenied,
  // The service has already been registered.
  kServiceHasBeenRegistered,
  // The service cannot be found.
  kServiceNotFound,
  // Unexpected os error.
  kUnexpectedOsError,
};