[cifs-protocol] [REG:110020359682290] [MS-RPRN] 3.1.4.1.2 Dynamically Typed Query Parameters - Bad variable names

[David Wooden]

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 
dwooden at microsoft.com 
425-704-5799
206-463-4674 (Mondays and Fridays)


-----Original Message-----
From: Jeremy Allison [mailto:jra at samba.org] 
Sent: Wednesday, February 03, 2010 3:30 PM
To: David Wooden
Cc: Jeremy Allison; pfif at tridgell.net; cifs-protocol at samba.org; 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: pfif at tridgell.net; cifs-protocol at samba.org
> 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.