server/protocol.def documentation

[James Hawkins]

On Wed, 09 Mar 2005 18:55:43 +0000, Mike Hearn <mike at navi.cx> wrote:
> There are no docs, AFAIK, but I found the file pretty self explanatory
> when I read it. Which bits do you find confusing? Maybe we can document
> only those parts.

I guess it's not so much that I can't understand it when I read
through the code and read the comments, but that we should document
this so whoever needs to work with the server next won't have to take
time to read through the necessary files to understand it.  There's
also a big possibility that I'm not understanding this correctly. 
Some things that would be nice to see in documentation are:

* server protocol design decisions (ie why we use do...while(0) loops
in SERVER_START_REQ as explained by Mike H)

* api like wine_server_add_data, wine_server_call
* adding a server function to protocol.def
* protocol.def: @REQ, @REPLY, @END
* protocol.def: VARARG...when to use it, syntax etc
* why we use DECL_HANDLER and what should go in it
* why there is a function and then its counterpart DECL_HANDLER

The biggest question I have right now (because I understand minimally
the points listed) is why api in protocol.def have different
parameters than there reg counterparts and even ntdll api:

/* Create a registry key */
@REQ(create_key)
    obj_handle_t parent;       /* handle to the parent key */
    unsigned int access;       /* desired access rights */
    unsigned int options;      /* creation options */
    time_t       modif;        /* last modification time */
    size_t       namelen;      /* length of key name in bytes */
    VARARG(name,unicode_str,namelen);  /* key name */
    VARARG(class,unicode_str);         /* class name */
@REPLY
    obj_handle_t hkey;         /* handle to the created key */
    int          created;      /* has it been newly created? */
@END

/* create a subkey */
/* warning: the key name must be writeable (use copy_path) */
static struct key *create_key( struct key *key, WCHAR *name, WCHAR *class,
                               int flags, time_t modif, int *created )


NTSTATUS WINAPI NtCreateKey( PHKEY retkey, ACCESS_MASK access, const
OBJECT_ATTRIBUTES *attr,
                             ULONG TitleIndex, const UNICODE_STRING
*class, ULONG options,
                             PULONG dispos )

And then you have DECL_HANDLER(create_key).

What I'm getting at is that these things are an integral part of wine,
and there isn't any documentation for it.  If someone would be willing
to write documentation for this topic, then wine and its developers
would definitely benefit.

-- 
James Hawkins