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

[David Wooden]

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.

Regards, 
David Wooden - Escalation Engineer - Microsoft Developer Support 
dwooden at microsoft.com 
425-704-5799
206-463-4674 (Mondays and Fridays)


-----Original Message-----
From: Bill Wesse 
Sent: Wednesday, February 03, 2010 8:25 AM
To: Jeremy Allison; Interoperability Documentation Help
Cc: pfif at tridgell.net; cifs-protocol at samba.org
Subject: RE: [Pfif] CAR: Bad variable names in MS-RPRN : 3.1.4.1.2 Dynamically Typed Query Parameters

Good day Jeremy - Thanks for your comments and questions about [MS-RPRN]; one of my team members will contact you shortly with the case number.

Regards,
Bill Wesse
MCSE, MCTS / Senior Escalation Engineer, US-CSS DSC PROTOCOL TEAM
8055 Microsoft Way
Charlotte, NC 28273
Email:	billwe at microsoft.com
Tel: 	+1(980) 776-8200
Cell: 	+1(704) 661-5438
Fax: 	+1(704) 665-9606

-----Original Message-----
From: Jeremy Allison [mailto:jra at samba.org] 
Sent: Tuesday, February 02, 2010 7:29 PM
To: Interoperability Documentation Help
Cc: pfif at tridgell.net; cifs-protocol at samba.org; jra at samba.org
Subject: [Pfif] CAR: Bad variable names in MS-RPRN : 3.1.4.1.2 Dynamically Typed Query Parameters

Dear Dochelp,

In MS-RPRN, section : 3.1.4.1.2 Dynamically Typed Query Parameters.

the text reads:

------------------------------------------------------------
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:

BUFFER: A buffer into which the server copies the requested dynamically-typed values. The term
"BUFFER" is used here as a placeholder. Each method section defines which of its parameters is
the pointer to the buffer.

pType: An optional pointer to a variable that receives a code that indicates the type of data that
is stored in the specified value. For a list of possible type values, see section 2.2.3.9.

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. For methods capable of returning more than one dynamically-typed
value, the caller also passes in:

pcReturned: A pointer to a variable into which the server copies the number of dynamically-typed
values that were written to the buffer, if the buffer was large enough to hold them.

The individual method sections include the following parameter validation steps by reference:
The server MUST verify that the value of cbBuf is not smaller than the number of bytes required
to hold the dynamically-typed values to be written to the buffer.

If that verification fails, the server MUST write the number of bytes required into the variable
that is pointed to by pcbNeeded and return ERROR_MORE_DATA.

If the value of cbBuf is not zero, the server MUST verify that a non-NULL pointer to the buffer
was passed in. If that verification fails, the server MUST return ERROR_INVALID_USER_BUFFER.
------------------------------------------------------------

I believe the references to the variable name "cbBuf" in the above are
incorrect, and should be replaced with "nSize" or with "cbData".

There is no variable name cbBuf defined in this section. It appears to
be a cut-and-paste error from "3.1.4.1.7 String Query Parameters", which
does define the "cbBuf" variable name.

Please let me know if this is correct.

Thanks,

Jeremy.