diff --git a/docs/dev/ExtendingTheIceInterface.md b/docs/dev/ExtendingTheIceInterface.md index 3ee879db9..21ca58a6c 100644 --- a/docs/dev/ExtendingTheIceInterface.md +++ b/docs/dev/ExtendingTheIceInterface.md @@ -13,8 +13,8 @@ The files involved in extending the Ice interface are | `MumbleServer.cpp` | Contains some boilerplate and Ice-internal implementation code. This file is automatically generated. | | `MumbleServerI.h` | Contains the definition of the actually implemented API classes (`ServerI` and `MetaI`). These extend the abstract base classes from `MumbleServer.h` | | `MumbleServerWrapper.cpp` | Contains wrapper implementation of the `*I` API classes. This file is automatically generated. | -| `MumbleServere.h` | Contains the definition of a statically used helper class | -| `MumbleServere.cpp` | Contains the implementation of that helper class **and** _static_ functions used to actually implement the server-side functionality of the Ice API functions | +| `MumbleServer.h` | Contains the definition of a statically used helper class | +| `MumbleServer.cpp` | Contains the implementation of that helper class **and** _static_ functions used to actually implement the server-side functionality of the Ice API functions | | `RPC.cpp` | Contains the implementations of the `Server` (the Mumble server, _not_ the Ice API type) class's member functions that are required to make certain functionality accessible to the static functions in `MumbleServerIce.cpp` | All auto-generated functions will end up in the corresponding directory inside the `build` directory. @@ -62,10 +62,26 @@ Error reporting works via the `cb->ice_exception` function and if everything wen In general it is a good idea to have a look at the existing implementation inside `MumbleServerIce.cpp` and take inspiration from those. Note that the implementations make heavy use of macros (e.g. `NEED_SERVER`, `NEED_CHANNEL`, etc.). These will initialize the corresponding variables -(`server`, `channel`, etc.) based in the parameters fed into the function (In order to obtain the channel, user, etc. you always have to initialize +(`server`, `channel`, etc.) based on the parameters fed into the function (In order to obtain the channel, user, etc. you always have to initialize the `server` variable first). For this to work it is essential that you are using the same parameter names as the existing implementations (e.g. `server_id` for the server's ID). (For historical reasons the macro to obtain the `user` variable is called `NEED_PLAYER`) +Furthermore, you might notice the macro definitions like `ACCESS_Server_isListening_READ`. These are used to determine what kind of access privilege +execution of the associated Ice function is required. By default, all functions are assumed to require write-privilege in order to be able to be +executed. The general form of these macros is +``` +ACCESS___ +``` +where +- `` and `` are used as defined above. They define which function this macro will be associated with. +- `` is the required access privilege. Possible values are `READ` and `ALL`, which allow function execution by anyone who has + read-privilege or simply everyone, regardless of their privileges. +The actual implementation of the access privilege checking is performed in the auto-generated `MumbleServerIceWrapper.cpp` based on whether an +associated macro is defined and if so, which one. +Please remember to `#undef` the respective macro at the end of the `MumbleServerIce.cpp` file in order to avoid macro definitions spilling into other +files when using unity builds. + + If the function requires action on the server's side (beyond its public API), you have to declare a new public function in the `Server` class (this time the Mumble server though; not the Ice server class) defined in `Server.h` (the definitions belong to the group of other RPC functions in there - section marked by a comment). The implementation of this new function should then be written in `RPC.cpp`.