// Copyright 2014 The Crashpad Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

#ifndef CRASHPAD_UTIL_MACH_NOTIFY_SERVER_H_
#define CRASHPAD_UTIL_MACH_NOTIFY_SERVER_H_

#include <mach/mach.h>

#include <set>

#include "util/mach/mach_message_server.h"

namespace crashpad {

//! \brief A server interface for the `notify` Mach subsystem.
//!
//! The <a
//! href="https://lists.apple.com/archives/darwin-development/2001/Sep/msg00451.html">mach
//! port notifications</a> thread on the <a
//! href="https://lists.apple.com/archives/darwin-development/">darwin-development</a>
//! mailing list (now known as <a
//! href="https://lists.apple.com/mailman/listinfo/darwin-dev">darwin-dev</a>)
//! is good background for the various notification types.
class NotifyServer : public MachMessageServer::Interface {
 public:
  //! \brief An interface that the different request messages that are a part of
  //!     the `notify` Mach subsystem can be dispatched to.
  //!
  //! Default implementations of all methods are available in the
  //! DefaultInterface class.
  class Interface {
   public:
    //! \brief Handles port-deleted notifications sent by
    //!     `mach_notify_port_deleted()`.
    //!
    //! A port-deleted notification is generated when a port with a dead-name
    //! notification request is destroyed and the port name becomes available
    //! for reuse.
    //!
    //! This behaves equivalently to a `do_mach_notify_port_deleted()` function
    //! used with `notify_server()`.
    //!
    //! \param[in] notify The Mach port that the notification was sent to.
    //! \param[in] name The name that formerly referenced the deleted port. When
    //!     this method is called, \a name no longer corresponds to the port
    //!     that has been deleted, and may be reused for another purpose.
    //! \param[in] trailer The trailer received with the notification message.
    virtual kern_return_t DoMachNotifyPortDeleted(
        notify_port_t notify,
        mach_port_name_t name,
        const mach_msg_trailer_t* trailer) = 0;

    //! \brief Handles port-destroyed notifications sent by
    //!     `mach_notify_port_destroyed()`.
    //!
    //! A port-destroyed notification is generated when a receive right with a
    //! port-destroyed notification request is destroyed. Rather than destroying
    //! the receive right, it is transferred via this notification’s \a rights
    //! parameter.
    //!
    //! This behaves equivalently to a `do_mach_notify_port_destroyed()`
    //! function used with `notify_server()`.
    //!
    //! \param[in] notify The Mach port that the notification was sent to.
    //! \param[in] rights A receive right for the port that would have been
    //!     destroyed. The callee takes ownership of this port, however, if the
    //!     callee does not wish to take ownership, it may set \a
    //!     destroy_request to `true`.
    //! \param[in] trailer The trailer received with the notification message.
    //! \param[out] destroy_request `true` if the request message is to be
    //!     destroyed even when this method returns success. See
    //!     MachMessageServer::Interface.
    virtual kern_return_t DoMachNotifyPortDestroyed(
        notify_port_t notify,
        mach_port_t rights,
        const mach_msg_trailer_t* trailer,
        bool* destroy_request) = 0;

    //! \brief Handles no-senders notifications sent by
    //!     `mach_notify_no_senders()`.
    //!
    //! A no-senders notification is generated when a receive right with a
    //! no-senders notification request loses its last corresponding send right.
    //!
    //! This behaves equivalently to a `do_mach_notify_no_senders()` function
    //! used with `notify_server()`.
    //!
    //! \param[in] notify The Mach port that the notification was sent to.
    //! \param[in] mscount The value of the sender-less port’s make-send count
    //!     at the time the notification was generated.
    //! \param[in] trailer The trailer received with the notification message.
    virtual kern_return_t DoMachNotifyNoSenders(
        notify_port_t notify,
        mach_port_mscount_t mscount,
        const mach_msg_trailer_t* trailer) = 0;

    //! \brief Handles send-once notifications sent by
    //!     `mach_notify_send_once()`.
    //!
    //! A send-once notification is generated when a send-once right is
    //! destroyed without being used.
    //!
    //! This behaves equivalently to a `do_mach_notify_send_once()` function
    //! used with `notify_server()`.
    //!
    //! \param[in] notify The Mach port that the notification was sent to.
    //! \param[in] trailer The trailer received with the notification message.
    //!
    //! \note Unlike the other notifications in the `notify` subsystem,
    //!     send-once notifications are not generated as a result of a
    //!     notification request, but are generated any time a send-once right
    //!     is destroyed rather than being used. The notification is sent via
    //!     the send-once right to its receiver. These notifications are more
    //!     useful for clients, not servers. Send-once notifications are
    //!     normally handled by MIG-generated client routines, which make
    //!     send-once rights for their reply ports and interpret send-once
    //!     notifications as a signal that there will be no reply. Although not
    //!     expected to be primarily useful for servers, this method is provided
    //!     because send-once notifications are defined as a part of the
    //!     `notify` subsystem.
    virtual kern_return_t DoMachNotifySendOnce(
        notify_port_t notify,
        const mach_msg_trailer_t* trailer) = 0;

    //! \brief Handles dead-name notifications sent by
    //!     `mach_notify_dead_name()`.
    //!
    //! A dead-name notification is generated when a port with a dead-name
    //! notification request is destroyed and the right becomes a dead name.
    //!
    //! This behaves equivalently to a `do_mach_notify_dead_name()` function
    //! used with `notify_server()`.
    //!
    //! \param[in] notify The Mach port that the notification was sent to.
    //! \param[in] name The dead name. Although this is transferred as a
    //!     `mach_port_name_t` and not a `mach_port_t`, the callee assumes an
    //!     additional reference to this port when this method is called. See
    //!     the note below.
    //! \param[in] trailer The trailer received with the notification message.
    //!
    //! \note When a dead-name notification is generated, the user reference
    //!     count of the dead name is incremented. A send right with one
    //!     reference that becomes a dead name will have one dead-name
    //!     reference, and the dead-name notification will add another dead-name
    //!     reference, for a total of 2. DoMachNotifyDeadName() implementations
    //!     must take care to deallocate this extra reference. There is no \a
    //!     destroy_request parameter to simplify this operation because
    //!     dead-name notifications carry a port name only (\a name is of type
    //!     `mach_port_name_t`) without transferring port rights, and are thus
    //!     not complex Mach messages.
    virtual kern_return_t DoMachNotifyDeadName(
        notify_port_t notify,
        mach_port_name_t name,
        const mach_msg_trailer_t* trailer) = 0;

   protected:
    ~Interface() {}
  };

  //! \brief A concrete implementation of Interface that provides a default
  //!     behavior for all `notify` routines.
  //!
  //! The Mach `notify` subsystem contains a collection of unrelated routines,
  //! and a single server would rarely need to implement all of them. To make it
  //! easier to use NotifyServer, a server can inherit from DefaultInterface
  //! instead of Interface. Unless overridden, each routine in DefaultInterface
  //! returns `MIG_BAD_ID` to indicate to the caller that the `notify` message
  //! was unexpected and not processed.
  class DefaultInterface : public Interface {
   public:
    DefaultInterface(const DefaultInterface&) = delete;
    DefaultInterface& operator=(const DefaultInterface&) = delete;

    // Interface:

    kern_return_t DoMachNotifyPortDeleted(
        notify_port_t notify,
        mach_port_name_t name,
        const mach_msg_trailer_t* trailer) override;

    kern_return_t DoMachNotifyPortDestroyed(
        notify_port_t notify,
        mach_port_t rights,
        const mach_msg_trailer_t* trailer,
        bool* destroy_request) override;

    kern_return_t DoMachNotifyNoSenders(
        notify_port_t notify,
        mach_port_mscount_t mscount,
        const mach_msg_trailer_t* trailer) override;

    kern_return_t DoMachNotifySendOnce(
        notify_port_t notify,
        const mach_msg_trailer_t* trailer) override;

    kern_return_t DoMachNotifyDeadName(
        notify_port_t notify,
        mach_port_name_t name,
        const mach_msg_trailer_t* trailer) override;

   protected:
    DefaultInterface() : Interface() {}
    ~DefaultInterface() {}
  };

  //! \brief Constructs an object of this class.
  //!
  //! \param[in] interface The interface to dispatch requests to. Weak.
  explicit NotifyServer(Interface* interface);

  NotifyServer(const NotifyServer&) = delete;
  NotifyServer& operator=(const NotifyServer&) = delete;

  // MachMessageServer::Interface:

  bool MachMessageServerFunction(const mach_msg_header_t* in_header,
                                 mach_msg_header_t* out_header,
                                 bool* destroy_complex_request) override;

  std::set<mach_msg_id_t> MachMessageServerRequestIDs() override;

  mach_msg_size_t MachMessageServerRequestSize() override;
  mach_msg_size_t MachMessageServerReplySize() override;

 private:
  Interface* interface_;  // weak
};

}  // namespace crashpad

#endif  // CRASHPAD_UTIL_MACH_NOTIFY_SERVER_H_