Thanks Jeremy - you bring up some great points. >> I'm not sure I follow the "API pattern" argument. I think each >> section should be specific to the variable names used above the >> phrase use. After all, the "API pattern" leads to the cut-and-paste >> error I just called out. Might be better to standardize the names >> across the document in all sections that use them.
I think the misunderstanding comes from the fact that this is a single section of the docs, which is trying to describe a pattern that is used by VERY many different API functions throughout Windows... """3.1.4.1.2 Dynamically Typed Query Parameters Unless notified otherwise, methods returning one or more dynamically-typed values use a common API pattern, in which the caller passes in the following parameters: . . . nSize or cbData: The size, in bytes, of the buffer. This value can be larger than the required size for the requested dynamically-typed values. pcbNeeded or pcbData: A pointer to a variable into which the server copies the number of bytes between the start of BUFFER and the last byte written by the server into BUFFER, both inclusive; or the required size of the buffer, in bytes, if the value of cbBuf is smaller than the size of the data to return to the caller. """ Unfortunately - the many different API functions that use this pattern, also use different parameter names for the buffer size (thus, the current "nSize or cbData", and, "pcbNeeded or pcbData" verbage). cbBuf is very commonly used and should be included here also. I wholeheartedly agree that the use of these different parameter names for the same purpose can lead to confusion and cut-and-paste errors like the one here. Unfortunately, the only perfect solution would be to standardize on one name, not in this document, but across the entire API set (and *then* in this document). For now, we will clean up this section in the documentation and make it consistent (with itself and with the API functions that use this pattern). Thank you again for bringing this problem to our attention. Please let me know if there is anything else I can do to help with this issue. Regards, David Wooden - Escalation Engineer - Microsoft Developer Support [email protected] 425-704-5799 206-463-4674 (Mondays and Fridays) -----Original Message----- From: Jeremy Allison [mailto:[email protected]] Sent: Wednesday, February 03, 2010 3:30 PM To: David Wooden Cc: Jeremy Allison; [email protected]; [email protected]; MSSolve Case Email Subject: Re: [REG:110020359682290] [MS-RPRN] 3.1.4.1.2 Dynamically Typed Query Parameters - Bad variable names On Wed, Feb 03, 2010 at 08:54:36PM +0000, David Wooden wrote: > Sorry for the re-send, adding our internal tool alias for tracking these > issues. > > -----Original Message----- > From: David Wooden > Sent: Wednesday, February 03, 2010 12:52 PM > To: Jeremy Allison > Cc: [email protected]; [email protected] > Subject: [REG:110020359682290] [MS-RPRN] 3.1.4.1.2 Dynamically Typed Query > Parameters - Bad variable names > > Hi Jeremy, > > I have created a case for this issue (case number is 110020359682290) and > will be working with you on it. > > In reading through this section, I believe that you are correct, since cbBuf > is not used previously in this section. > > > Since this section is talking about an API pattern rather than a specific API > function, it may be that the correct solution is to change... > > "pcbNeeded or pcbData:" > > to > > "pcbNeeded or pcbData or cbBuf:" > > ...because cbBuf is certainly used by some functions in this pattern (as > described elsewhere in this document). > > > Please let me know your thoughts. In the meantime, I will dig a little > deeper and update you as soon as I have more to add. I'm not sure I follow the "API pattern" argument. I think each section should be specific to the variable names used above the phrase use. After all, the "API pattern" leads to the cut-and-paste error I just called out. Might be better to standardize the names across the document in all sections that use them. Jeremy. _______________________________________________ cifs-protocol mailing list [email protected] https://lists.samba.org/mailman/listinfo/cifs-protocol
