Re: server/protocol.def documentation
Juan Lang [EMAIL PROTECTED] writes: As far as documenting the server API, again I agree with you: it's a worthwhile task. There's even a todo list item for it assigned to Alexandre.. but I wouldn't hold my breath for him to provide something parseable by newbies. protocol.def itself is the documentation of the protocol, there is no need for more. It's pretty much self-explaining anyway, and people who can't figure it out by reading the code have no business messing around with the server protocol. Consider it as the entrance exam for server hacking ;-) -- Alexandre Julliard [EMAIL PROTECTED]
Re: server/protocol.def documentation
--- Alexandre Julliard [EMAIL PROTECTED] wrote: protocol.def itself is the documentation of the protocol, there is no need for more. It's pretty much self-explaining anyway, and people who can't figure it out by reading the code have no business messing around with the server protocol. Consider it as the entrance exam for server hacking ;-) Okay, fair enough. I think what's missing, though, is a dev guide entry on where this thing is, and (briefly) how to extend it. But since experienced wine hackers seem to figure this out anyway, there may be no need. --Juan __ Do you Yahoo!? Yahoo! Small Business - Try our new resources site! http://smallbusiness.yahoo.com/resources/
Re: server/protocol.def documentation
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.
Re: server/protocol.def documentation
On Wed, 09 Mar 2005 18:55:43 +, Mike Hearn [EMAIL PROTECTED] 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
Re: server/protocol.def documentation
Hi James, ie why we use do...while(0) loops in SERVER_START_REQ This is a fairly common idiom in C macros. See here for an explanation: http://www.everything2.com/index.pl?node_id=1180050 Because it's a common trick, I'm not sure it's worth explaining. Describing at a high level what SERVER_START_REQ and SERVER_END_REQ do for the macro-phobic might be useful though. As far as documenting the server API, again I agree with you: it's a worthwhile task. There's even a todo list item for it assigned to Alexandre.. but I wouldn't hold my breath for him to provide something parseable by newbies. If you're starting to understand it, maybe writing it down would be a good idea. --Juan __ Do you Yahoo!? Yahoo! Small Business - Try our new resources site! http://smallbusiness.yahoo.com/resources/
Re: server/protocol.def documentation
James Hawkins wrote: 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. It's not commented because the comments can become out of date and misleading. If you want to modify Wine's internals, then you'd better take the time to thoroughly read and understand the code. Mike
server/protocol.def documentation
Hi, I now understand the purpose of SERVER_START_REQ et al, but now I'm in server/protocol.def and I'm trying to add a protocol definition for load_key. load_key is implemented in server/registry.c, but is not in server/protocol.def so, if I'm correct, I can't make a call to load_key from ntdll yet. I am trying to add load_key to protocol.def, but I don't know the semantics of this file. Is there any documentation available for this topic, or does anyone have any information that could be added to the docs? -- James Hawkins
Re: server/protocol.def documentation
On Tue, Mar 08, 2005 at 06:38:01PM -0600, James Hawkins wrote: Hi, I now understand the purpose of SERVER_START_REQ et al, but now I'm in server/protocol.def and I'm trying to add a protocol definition for load_key. load_key is implemented in server/registry.c, but is not in server/protocol.def so, if I'm correct, I can't make a call to load_key from ntdll yet. I am trying to add load_key to protocol.def, but I don't know the semantics of this file. Is there any documentation available for this topic, or does anyone have any information that could be added to the docs? I think you should be looking at dlls/advapi32/registry.c::RegLoadKeyW() for a registry load key implementation. It is using the load_registry request. Ciao, Marcus
Re: server/protocol.def documentation
On Wed, 9 Mar 2005 07:34:16 +0100, Marcus Meissner [EMAIL PROTECTED] wrote: On Tue, Mar 08, 2005 at 06:38:01PM -0600, James Hawkins wrote: Hi, I now understand the purpose of SERVER_START_REQ et al, but now I'm in server/protocol.def and I'm trying to add a protocol definition for load_key. load_key is implemented in server/registry.c, but is not in server/protocol.def so, if I'm correct, I can't make a call to load_key from ntdll yet. I am trying to add load_key to protocol.def, but I don't know the semantics of this file. Is there any documentation available for this topic, or does anyone have any information that could be added to the docs? I think you should be looking at dlls/advapi32/registry.c::RegLoadKeyW() for a registry load key implementation. It is using the load_registry request. Ciao, Marcus I looked at RegLoadKeyW/A, but I don't know why load_registry was chosen over load_key. If the common opinion is that we use load_registry instead of load_key, I can do that (it would be easier anyway), but the plan is to implement NtLoadKey and have RegLoadKey call NtLoadKey. -- James Hawkins
