Interface DaveSession

public interface DaveSession
Implementation for the Discord Audio & Video End-to-End Encryption (DAVE) Protocol.
See Also:

  • Method Details

    • getMaxProtocolVersion

      int getMaxProtocolVersion()
      The maximum supported version of the DAVE protocol.
      Returns:
      Maximum supported version

    • getMaxEncryptedFrameSize

      int getMaxEncryptedFrameSize(@Nonnull DaveSession.MediaType type, int frameSize)
      Calculate the maximum encrypted size for the provided frame.

      This is used to ensure the ByteBuffer provided to encrypt(MediaType, int, ByteBuffer, ByteBuffer) has enough space for the encrypted data.

      Parameters:
      type - The DaveSession.MediaType of the frame
      frameSize - The size of the encoded frame
      Returns:
      The maximum number of bytes an encrypted frame will need

    • getMaxDecryptedFrameSize

      int getMaxDecryptedFrameSize(@Nonnull DaveSession.MediaType type, long userId, int frameSize)
      Calculate the maximum decrypted size for the provided frame.

      This is used to ensure the ByteBuffer provided to decrypt(MediaType, long, ByteBuffer, ByteBuffer) has enough space for the decrypted data.

      Parameters:
      type - The DaveSession.MediaType of the frame
      userId - The id for the user that sent this frame
      frameSize - The size of the encrypted frame
      Returns:
      The maximum number of bytes a decrypted frame will need

    • assignSsrcToCodec

      void assignSsrcToCodec(@Nonnull DaveSession.Codec codec, int ssrc)
      Associates a media DaveSession.Codec with a given SSRC (synchronization source).

      This mapping is used by the implementation to select the correct codec for incoming or outgoing media identified by the specified ssrc.

      Parameters:
      codec - The codec that should be used for the given SSRC
      ssrc - The SSRC value provided by the voice gateway

    • encrypt

      boolean encrypt(@Nonnull DaveSession.MediaType mediaType, int ssrc, @Nonnull ByteBuffer data, @Nonnull ByteBuffer encrypted)
      Encrypts the plaintext frame and writes the encrypted data into encrypted.

      Implementations should read the remaining bytes from data starting at its current position, and write the resulting encrypted payload into encrypted starting at its current position.

      The caller is responsible for ensuring that encrypted has sufficient remaining capacity to receive the encrypted frame, which can be determined via getMaxEncryptedFrameSize(MediaType, int).

      After successfully encrypting the data, the encrypted buffer should have its position at the beginning of the encrypted data and its limit at the end of the encrypted data. (Usually achieved by calling Buffer.flip())

      Parameters:
      mediaType - The media type of the data
      ssrc - The SSRC (synchronization source) of the sender
      data - The direct buffer containing the data to encrypt
      encrypted - The direct buffer to fill with the encrypted data (with enough space for max encrypted frame size).
      Returns:
      True, if the encryption was successful

    • decrypt

      boolean decrypt(@Nonnull DaveSession.MediaType mediaType, long userId, @Nonnull ByteBuffer encrypted, @Nonnull ByteBuffer decrypted)
      Decrypts an Opus-encoded audio frame received from the network.

      Implementations should read the remaining bytes from encrypted starting at its current position, and write the resulting decrypted payload into decrypted starting at its current position.

      The caller is responsible for ensuring that decrypted has sufficient remaining capacity to receive the decrypted frame, which can be determined via getMaxDecryptedFrameSize(MediaType, long, int).

      After successfully decrypting the data, the decrypted buffer should have its position at the beginning of the decrypted data and its limit at the end of the decrypted data. (Usually achieved by calling Buffer.flip())

      Parameters:
      mediaType - The media type of the encrypted data
      userId - The id for the user that sent this frame
      encrypted - The direct buffer containing encrypted data
      decrypted - The direct buffer to fill with the decrypted data (with enough space for max decrypted frame size)
      Returns:
      True, if the decryption was successful

    • addUser

      void addUser(long userId)
      Add a new recognized user for the MLS group.
      Parameters:
      userId - The user id of the new member
      See Also:

    • removeUser

      void removeUser(long userId)
      Remove a user from the MLS group.
      Parameters:
      userId - The user id to remove
      See Also:

    • initialize

      void initialize()
      Called when the connection is established.

      Can be used to track timeouts before the first call to onSelectProtocolAck(int).

    • destroy

      void destroy()
      Called when the session is no longer needed and all related resources should be cleaned up.

    • onSelectProtocolAck

      void onSelectProtocolAck(int protocolVersion)
      Handle SELECT_PROTOCOL_ACK/SESSION_DESCRIPTION (opcode 4).
      Parameters:
      protocolVersion - The protocol version to transition to
      See Also:

    • onDaveProtocolPrepareTransition

      void onDaveProtocolPrepareTransition(int transitionId, int protocolVersion)
      Handle DAVE_PROTOCOL_PREPARE_TRANSITION (opcode 21).

      Sent when a protocol transition should be prepared. Followed by onDaveProtocolExecuteTransition(int) once all group members are ready for transition

      Parameters:
      transitionId - The transition id, to be referenced later by onDaveProtocolExecuteTransition(int)
      protocolVersion - The target protocol version to transition to
      See Also:

    • onDaveProtocolExecuteTransition

      void onDaveProtocolExecuteTransition(int transitionId)
      Handle DAVE_PROTOCOL_EXECUTE_TRANSITION (opcode 22).

      Sent when a transition should be executed. This is usually preceded by onDaveProtocolPrepareTransition(int, int).

      Parameters:
      transitionId - The transition id, previously registered by onDaveProtocolPrepareTransition(int, int)
      See Also:

    • onDaveProtocolPrepareEpoch

      void onDaveProtocolPrepareEpoch(long epoch, int protocolVersion)
      Handle DAVE_PROTOCOL_PREPARE_EPOCH (opcode 24).

      Sent from the server to clients to announce upcoming protocol version changes. When the epoch ID is equal to 1, this message indicates that a new MLS group is to be created for the given protocol version.

      Parameters:
      epoch - The epoch used by the session (equal to 1 to indicate a new MLS group should be created)
      protocolVersion - The protocol version for the new MLS group
      See Also:

    • onDaveProtocolMLSExternalSenderPackage

      void onDaveProtocolMLSExternalSenderPackage(@Nonnull ByteBuffer externalSenderPackage)
      Handle MLS_EXTERNAL_SENDER_PACKAGE (opcode 25).

      Includes the basic credential and public key for the voice gateway external sender to be added to the MLS group's extensions.

      Parameters:
      externalSenderPackage - Binary representation for the external sender package
      See Also:

    • onMLSProposals

      void onMLSProposals(@Nonnull ByteBuffer proposals)
      Handle MLS_PROPOSALS (opcode 27).

      Includes a list of proposals to be appended or a list of proposal refs to be revoked.

      Parameters:
      proposals - Binary representation for the proposals
      See Also:

    • onMLSPrepareCommitTransition

      void onMLSPrepareCommitTransition(int transitionId, @Nonnull ByteBuffer commit)
      Handle MLS_PREPARE_COMMIT_TRANSITION (opcode 29).

      Includes the MLS commit being broadcast to move to the next epoch.

      Parameters:
      transitionId - The transition id for the commit transition
      commit - Binary representation of the commit message
      See Also:

    • onMLSWelcome

      void onMLSWelcome(int transitionId, @Nonnull ByteBuffer welcome)
      Handle MLS_WELCOME (opcode 30).

      Includes the MLS Welcome which adds the pending member to the group

      Parameters:
      transitionId - The transition id for the welcome transition
      welcome - Binary representation of the welcome message
      See Also: