[quote=105156:@Tim Jones]@Paul Lefebvre - Another example of how scattered this information is. That is non-intuitive and I thought that the SMTPSecureSocket.Secure property was a read-only property to determine if the connection was secure.
That will simplify things drastically.[/quote]
Why is it not intuitive? And where is the information scattered at? It’s all right in the docs, read-only properties even have a Lock icon by them in the overview, of which Secure does not. Viewing the docs on secure it shows the syntax as being able to read and write and the example is one of setting the value in source.
When I go to develop something or use a new class, my first stop is the API docs. Only when I can’t find information there do I start searching the forums/web.
To determine what you’ve just stated, a user would need to:
a) Know that an SSLSecureSocket can be used in a non-secure manner
b) Knowing that, would have clicked on the “Secure” property to read its description.
That is what’s not intuitive.
Also, since the SMTPSecureSocket will perform in both modes, why are there separate entities for secure and non-secure operations?
[quote=105201:@Tim Jones]To determine what you’ve just stated, a user would need to:
a) Know that an SSLSecureSocket can be used in a non-secure manner
b) Knowing that, would have clicked on the “Secure” property to read its description.
That is what’s not intuitive.
Also, since the SMTPSecureSocket will perform in both modes, why are there separate entities for secure and non-secure operations?[/quote]
One would have to go and read the docs on SMTPSecureSocket, that’s all. No need to “know” the information ahead of time, if you knew it you wouldn’t have to go look. As for the name, the “Secure” name seems interesting, is read/write, something I can change, so I’d just click it and read.
As for why… I do not know the internals of how it works, so I can not answer.
I guess my point is that the docs contain all the information you need. Learning to read them and use them can take some practice, but once done it can give you a HUGE jump in ones productivity and knowledge base as a developer. It really is worth spending time in the docs. In fact, I routinely just go read the docs for the fun of it. It always pays off in large dividends in productivity and knowledge.
Jeremy, you misunderstand the reason behind this thread. Everything can be found if you know where to go and what you’re looking for is called. What I’m shooting for is a “This is how you send or receive Email in a Xojo App” top level for new users. Currently, the questions that I see coming from new users all tend to the same basic points - one of these is “How do I handle email?” A new developer knows the term Email. However, is it obvious or intuitive that such a thing as an SMTPSecureSocket class, that is a subclass of an SSLSocket class, that is a subclass of a TCPSocket class, that is a subclass of a SocketCore object is where to start? And that this is where you should start to deal with connections that require secure, SSL connections.
Obviously (to me and a couple of 9th graders I’m tutoring at least), there needs to be a better high level document that answers the questions of “which APIs do I use to … ?” This is what I’m trying to build. Being told that something is obvious when it obviously isn’t is one of the issues that I’m trying to improve upon.
And there’s no need to defend Paul’s efforts. I am very aware of how far the docs have come since he took the reigns. However, much of what’s there is still documented from a “developer that knows what’s going on” perspective.
What you’re looking for should be covered in the User’s Guide, not found in the Language Reference. There is a brief discussion in Book3: Fundamentals, Section 5: Email that points the user to SMTPSocket and SMTPSecureSocket. It also notes the thing that I’ve seen trip up most users, that you have to get the specifics of the connection from your provider.