[gnutls-dev] Re: API comments

[Simon Josefsson]

Nikos Mavroyanopoulos <nmav at hellug.gr> writes:

> On Tue, 4 Dec 2001 20:18:51 +0100 (CET) Simon Josefsson <jas at vic20.blipp.com> wrote:
>
>> > It says that "Returns the number of bytes sent, or a negative error code.",
>> > but it may still not be clear. What do you propose?
>> The complete documentation also say:  The function has the same semantics
>> as read() has.  This simply isn't true, it returns
>> GNUTLS_E_{INTERRUPTED,EAGAIN} which read() doesn't do.  Those error codes
>> aren't mentioned in the read() documentation either.
> I'll make the documentation more precise.

Thank you.

>> My suggestion would be to not mess with the return values for read() and
>> write(), it would be simpler to replce TCP read()/write() with TLS if it
>> was this way, and the TLS libraries I've used worked this way /as far as I
>> can remember anyway).
> Well I don't think that this would do much good. I'll have to use an errno
> variable to report errors (and other messages like rehandshake). That's an
> extra variable to cope with. Why don't you like the negative error codes?

I don't like having a different interface than read() and write().
When porting code it is advantageous if you can re-use the read/write
logic of the code even when TLS is used.

>> > > I think it would be nice if they did work as
>> > > read() and write(), I believe both Open SSL and Mozilla NSS do that.
> Well some implementations use something like tls_bind() or tls_accept().
> These have no meaning in TLS or SSL.

This solution is much worse, yes.

> Also tls_read() and tls_write() need to report many more things than
> the normal TCP/IP read() and write().  Thus I've decided to create
> an API that relates to TLS and not TCP (but still has a lot of
> similarities). Anyway I think that it is important for developers to
> know some things about tls before using any tls layer library.  (at
> least as much as sockets developers know about tcp/ip)

Right.  Maybe the TLS specific return codes could be conveyed using
another variable like "errno".  Hm.

>> > I'm trying not to tight gnutls to berkeley style sockets, or even TCP/IP.
>> Good. The type name "SOCKET" always bothered me.
> I've renamed this to GNUTLS_SOCKET_PTR (gnutls is there to avoid namespace polution).

Ok.  I still find the term "SOCKET" a bit TCP specific though, since
it should be specific to "sockets".

Sorry if my tone sounds harsh, these are only thoughts and I didn't
put much effort into thinking this through either.  I understand
designing a API is non-trivial.