[Pcsclite-muscle] API Docs improvement

[Maksim Ivanov]

Hello Ludovic,

Thanks for the fast replies!


I additionally checked the code examples and found a couple of small issues:

* Code example for SCardCancel: the sample looks like SCardCancel is
called on the same thread as SCardGetStatusChange, which shouldn't
happen probably. Also the SCardGetStatusChange argument values are a
bit misleading: dwTimeout=0 means that no actual waiting will occur
(and, hence, no cancellation is useful), rgReaderStates receives
SCARD_READERSTATE instead of LPSCARD_READERSTATE, and
cReaders=cReaders is not initialized to 1 in the sample code.

* Code example for SCardControl: missing comma in pbSendBuffer assignment.

* Code example for SCardListReaders: missing semicolon after
assignment to dwReaders.


What else I badly missed in the PC/SC-Lite docs is the clear
description of what arguments are optional (i.e. can be NULL instead
of the real pointers). Often this follows from the textual description
of the function, or can be guessed. And in some cases this information
cannot be derived from the context at all (like pioRecvPci argument of
the SCardTransmit function).

It would be great if this information would be easily available in the
"Parameters" section of each function's description.


Regards,
Maksim


On Fri, Mar 11, 2016 at 10:34 AM, Ludovic Rousseau
<ludovic.rousseau at gmail.com> wrote:
>
> 2016-03-09 18:47 GMT+01:00 Maksim Ivanov <emaxx at google.com>:
>>
>> Hello all,
>
>
> Hello Maksim,
>
>>
>> Several improvement suggestions for the PC/SC-Lite API documentation:
>>
>> * SCardGetStatusChange: Indicate that the return code SCARD_E_CANCELLED is
>> possible.
>
>
> Fixed in f590a950283ca46cb0f3e8b3a640254c61f31ff2
>
>>
>>
>> * SCardEstablishContext: the mentioned SCARD_SCOPE_GLOBAL value of the
>> dwScope argument is not defined in any public header file.
>
>
> Fixed in  a9dbb3c3ca1527228711f3e6c61fee15a1a80971
>
>>
>> * SCardStatus: There is some mess regarding whether the reader name is a
>> multi-string or a simple string: the argument mszReaderName is sometimes
>> referred as szReaderName; the documentation of the pcchReaderLen argument
>> also says "multistring".
>
>
> Fixed in  2a80f615fc5084838a9c299609fa468772fae71b
>
>>
>> * SCardTransmit: the pioSendPci argument is marked as [in,out], while
>> actually it's an input-only argument (it's even a pointer-to-const).
>
>
> Fixed in  bfc6c15ec7b5941efaa48a1c1e5ff7d2cd8b0fa4
>
>>
>> * SCardTransmit: the example code passes a pointer to uninitialized
>> SCARD_IO_REQUEST structure as the pioRecvPci argument value - while it's an
>> in-out argument (and the SCardTransmit implementation actually reads data
>> from it).
>
>
> Fixed in  aed8486d13da8de4a77b620e28c617cc9cb18cd9
>
>>
>> * SCardListReaderGroups: It is stated that SCARD_E_INVALID_PARAMETER is
>> returned when the mszGroups argument value is NULL, while it doesn't mention
>> that this only happens when *pcchGroups is equal to SCARD_AUTOALLOCATE.
>
>
> Fixed in  43bac6981940ae3e8f05122342df6515aacb7fe8
>
> Thanks. Great work.
>
> --
>  Dr. Ludovic Rousseau
>
> _______________________________________________
> Pcsclite-muscle mailing list
> Pcsclite-muscle at lists.alioth.debian.org
> http://lists.alioth.debian.org/cgi-bin/mailman/listinfo/pcsclite-muscle


Maksim Ivanov

Software Engineer

emaxx at google.com
+49 (0)176 65889070

Google Germany GmbH

Dienerstra?e 12

80331 M?nchen


Gesch?ftsf?hrer: Matthew Scott Sucherman, Paul Terence Manicle

Registergericht und -nummer: Hamburg, HRB 86891

Sitz der Gesellschaft: Hamburg


Diese E-Mail ist vertraulich. Wenn Sie nicht der richtige Adressat
sind, leiten Sie diese bitte nicht weiter, informieren Sie den
Absender und l?schen Sie die E-Mail und alle Anh?nge. Vielen Dank.



This e-mail is confidential. If you are not the right addressee please
do not forward it, please inform the sender, and please erase this
e-mail including any attachments. Thanks.