BREW POP / SMTP Mailer Appendix - 6 / 6 -
Note
The SophiaFramework UNIVERSE classes of interest here are the SFXSmtpSender class for sending mail, the SFXPop3Receiver class for receiving mail and the SFBTextCtl class for handling text.
* This appendix assumes readers have already gone through both the HelloWorld and Cartoon tutorials.
SimpleMailer Class
The SimpleMailer class inherits from SFRApplication.
The variable _option, of type SFXConfig, is declared to save the setup data ( address of SMTP server, etc. ) of the application. SFXConfig class objects act as setup files, managing information through entries consisting of a tag( ID ) and value.
The variable _mail, of type SFXProperty, is used to access a specific mail entry from a list of received mails. SFXProperty class objects manage strings through keys.
The SFXConfigPtr GetOption( ), returns a reference to the entire setup list in _option.
The SFXPropertyPtr GetMail( ), returns a referance to the mail specified by a given key.
The constructor is declared explicitly using exception handling, in case _option is not properly loaded.
MainWindow Class
MainWindow.hpp
The MainWindow class inherits from SFRTitleWindow, the responder class that displays a window with a title.
The variable _receiver, of type SFXPOP3Receiver, is used to receive mail messages using POP3 protocol. Using this variable frees the developer from needing to worry about the details of POP3 protocol.
The next variable _dialog, of type SFRMessageDialogPtr, is used to display a message along with a button in a textbox.
The rest of the header file declares the constructor / destructor, the handlers and a POP3 receiver callback function POP3Callback.
MainWindow Constructor
-
The MainWindow constructor first uses the SFRTitleWindow constructor to create a main window with the title "Simple Mailer".
The font height is obtained through the SFXGraphics GetFontHeight( ) function, and saved in the Sint16 type variable fontHeight. The variable width calculates the width of the message arbitrary message "Send", through the SFXGraphics MeasureText( ) function.
Both fontHeight and width are used to calculate the dimensions of a rectangle large enough to accommodate all the displayed main option strings.
Four buttons ( "Send", "Receive", "Setup" and "End" ) are created using the SFRButtonControl constructor and are managed by SFRButtonControlPtr pointers.
Handlers for each button are registered in the same way using exception handling. Their event type is SREVT_CONTROL, their timing is HANDLER_BEFORE and the handler function they use is OnButtonControl.
The focus of button number one ( "Send" ), is set as the default focused object.
MainWindow Event Handlers
Key Handler
-
The MainWindow key handler does not introduce any new concepts.
An "Up key" press moves the focus up by calling the FocusUp( ) function, while a "Down key" press moves the focus down by way of the FocusDown( ) function.
Both these functions, inherited from the SFRResponder class, shift focus to the next nearest responder respectively up and down. The Clear key calls the Terminate( ) function and terminates this window.
* Clicking any of the buttons on the left, displays their window sequence diagrams.
Send Button Handler
The handler for the "Send" button, simply creates a new SendingWindow( ) where mail-sending procedures are defined and executed.
Receive Button Handler
-
The handler for the "Receive" button, obtains the _option list through the GetOption( ) function and saves it in a new loval variable option.
The mail server account information is established through the SFXPOP3Receiver SetAccount( ) function, which reads the user name and password from the option file.
Next the SFXPOP3Receiver SetServer( ) function, sets the IP address and port number of the POP3 server through a SFXSocketAddress object. The domain name is automatically resolved by the Connect( ) function of the SFXTCPSocket class, which inherits from SFXSocketAdress.
The SFXConfig ReadBool( ) function, used to read a Boolean value from an SFXconfig file, is used to read OPTION_ERASEMAIL. If it is false, then the SFXPOP3Receiver Receive( ) function is called to receive the mail. Else, the SFXPOP3Receiver ReceiveAndDelete( ) function is called to receive the mail and delete it right away.
Both these functions have return values to signal success ( SFERR_NO_ERROR ), or to signal a cause of error ( ex. SFERR_NO_MEMORY ). In case of success, a "Receiving..." message is displayed, and in case of failure, a "Reception failed" message is displayed.
The event diagram above starts with the focus on the "End" button of the MainWindow. Only MainWindow is navigated, so no other windows are created and all events are handled there.
Setup Button Handler
When the "Setup" button is pressed, this handler generates a new OptionWindow( ) where setup procedures are defined and executed.
End Button Handler
When the "End" button is pressed, the SFRApplication Terminate( ) function is called and the application is ended.
Dialog Handler
The dialog handler invokes an SREVT_RESPONDER_TERMINATE event to close the dialog box. It then creates a new RceivingWindow( ) and finally invokes an SREVT_RESPONDER_RENDER event to redraw the screen.
Callback for Receiving Mail
CALLBACK_IMPLEMENT_SFXPOP3RECEIVER is the macro that defines the implementation of the POP3 mail receiving callback function.
Its arguments are the class name ( MainWindow ), the callback ( POP3Callback ) and an SFXError type variable ( error ).
It closes the "Receiving..." dialog, and if reception was successful, it sets the SFXWideString variable message to "Successful reception". In case of errors, "Reception failed" is set.
The appropriate message is displayed, and for successful reception, the dialog handler is called when the "OK" button is pressed.
A reference to the received mail is obtained through the GetMail( ) function and each received mail is saved along with its key into the local variable mail. An SREVT_RESPONDER_RENDER event is invoked to redraw the screen.
OptionWindow Class
OptionWindow.hpp
OptionWindow also inherits from SFRTitleWindow.
It declares six SFRBrewTextControlPtr pointers that will each point to a specific text control in OptionWindow. An SFRCheckboxControl _checkboxEraseMail is also declared.
The rest of the header file declares the constructor / destructor, and the handler functions.
OptionWindow Constructor
-
The setup data is once again obtained using the GetOption( ) function and saved in yet another local option variable. Key handler registration and text box dimensions are all processed in similar ways as in the MainWindow class.
Two SFXRectangle objects, rectLeft and rectRight, are used throughout this constructor to input the coordinates of the text boxes. Labels for the first two text boxes are made by the SFRLabelControl constructor, using rectLeft and rectRight as arguments.
The y coordinates of rectLeft and rectRight are then shifted down and used as arguments to the SFRBrewTextControl( ) constructor which creates the first two text controls. The other arguments of this constructor are an SFRResponder pointer and an SFXAnsiString object which contains data defining behavior, attributes and a wide string for initialization. This process is repeated for all six text controls.
_checkboxEraseMail is created with the SFRCheckboxControl constructor, which allows for direct labeling. Its default status is set to false, meaning mail is not deleted when it is received. The buttonOk and buttonCancel buttons are created using the SFRButtonControl constructor and need only a responder pointer, rectangle and label to be specified.
The max size of entries for each text control is set after error checking ( the focus is set on _textControlSMTPServer by default ). Handlers for each button control are also registered.
The SelectHandler of the SFRResponder class is registered to handle all Select key events. This is a SophiaFramework UNIVERSE handler that needs not be defined, and automatically gives focus to the appropriate UI object when the Select key is pressed.
OptionWindow Event Handlers
Key Handler
An "Up key" press moves the focus to the previous responder by calling the FocusPrevious( ) function, while a "Down key" press moves the focus to the next responder by way of the FocusNext( ) function.
Both these functions, inherited from the SFRResponder class, shift focus respectively to the responder that came before it and after it.
Save Button Handler
-
This handler starts by obtaining the _option list through the GetOption( ) function, and saves it in the local variable option.
It writes the updated setup names into the option file through the SFXConfig WriteSFXAnsiString function. The arguments of this function are the output destination and the text to be written ( obtained from the text control by the SFBTextCtl GetText( ) function ).
The updated setup numbers are written to the option file by the SFXConfig WriteUInt16( ) function. The number data must be casted as UInt16 to use this function.
An SREVT_RESPONDER
_TERMINATE event is invoked to close the OptionWindow.The event diagram on the left starts assuming that the focus is on the "Password" text box of the OptionWindow
The Select key event is handled automatically by the select handler, and text input is handled by the BREW native ITextCtl class.
The rest of the events are handled by the OptionWindow.
* ITextCtl event handling is not shown here for simplicity.
Cancel Button Handler
The Cancel button handler terminates the OptionWindow by invoking an SREVT_RESPONDER_TERMINATE event.
ReceivedWindow Class
Received Window.hpp
ReceivedWindow inherits from SFRPlainWindow, meaning it will not have a title displayed at the top of the window. The Sint32 _index variable is declared to manage which mail message is displayed.
The rest of the header file declares the constructor / destructor and the handler functions.
ReceivedWindow Constructor
-
The ReceivedWindow constructor first creates a new window using the constructor of the SFRPlainWindow class and initializes _index to 0. The key handler and drawing handler are registered as usual.
The SetVirtualBound( ) of the SFRMessageDialog class is used to set up a virtual region that can be scrolled vertically. A thousand is added to the height value to accommodate long emails.
ReceivedWindow Event Handlers
Drawing Handler
The GetMail( ) function is used to obtain a reference to the specific mail that is requested, and this reference is saved in the SFXPropertyPtr mail.
After the background is cleared, the mail is displayed by the SFXGraphics DrawString( ) function. The arguments of this function are the string to draw ( SFXWideStringConstRef ), the rectangle containing the string ( SFXRectangleConstRef ), the drawing color ( SFXRGBColorConstRef ), and the text alignment ( Uint32 ).
Key Handler
The key handler also obtains a reference to the requested mail, and saves it in its own local mail variable.
If the Clear key is pressed, SREVT_RESPONDER_TERMINATE is invoked to cancel the ReceivedWindow.
If the Up or Down directional keys are pressed, the SFRResponder scroll( ) function is called. This function scrolls respectively up or down by an SFXSize( ) value defined in its argument.
If the Left or Right directional keys are pressed, _index is respectively decremented or incremented and the screen is redrawn.
SendingWindow Class
SendingWindow.hpp
-
The SendingWindow declares four SFRBrewTextControl pointers to refer to its four text boxes. It also declares a MessageDialogPtr _dialog, to display messages along with a button.
The variable _sender of the mail sending class SFXSMTPSender is declared to manage mail sending.
The rest of the header file declares the constructor / destructor, and the SMTPCallback function.
SendingWindow Constructor
See OptionWindow constructor.
SendingWindow Event Handlers
Key Handler
See OptionWindow key handler.
Ok Button Handler
When the "Ok" button is pressed, a reference to the setup data is obtained through the GetOption( ) function and saved in the SFXConfigPtr option.
A variable ( message ) of type SFXMailMessage, the class that modifies and manages mail messages, is declared. SFXMailMessage member functions are used to set the "From", "To" and "Subject" fields, as well as the message "Body" itself.
_sender accesses the SFXSMTPSender SetServer( ) function, which sets the address and port number of the SMTP server.
The callback function SMTPCallback is called and returns its error value to the SFCError variable error. If there were no errors in the callback, a dialog with the message "Sending..." is displayed, and otherwise "Failed during transmission" is displayed. In the case of callback error, the dialog handler is also registered.
Cancel Button Handler
Invokes SREVT_RESPONDER_TERMINATE and cancels the SendingWindow.
Dialog Handler
The dialog handler invokes two SREVT_RESPONDER_TERMINATE events, one to close the dialog box, and one to cancel the SendingWindow. It then invokes SREVT_RESPONDER_RENDER to redraw the screen.
SMTPCallback Function
See MainWindow POP3Callback function.