GAMBAS BOOK 3.19.1

In this chapter you will be introduced to an SMTP client whose special feature is that you do not send an EMail directly but with the standard EMail programme of your system. Your advantage: You set the connection security and the required authentication method for the used e-mail account in the standard e-mail programme of the system.

The project uses the SendMail(…) method of the Desktop class of the component of the same name, which was already described in → Chapter 15.1.1.

Use the Desktop.SendMail(..) method to prepare an email and pass it to the system's default email client:

SendMail(TO As String[][,CC As String[], BCC As String[], Subject As String, Body As String, Attachment As String])

• TO is a list of recipients (string array).
• CC is another list (string array) of recipients with CC for carbon-copy
• BCC is another list (string array) of recipients with BCC for blind-carbon-copy
• Subject is the subject of the email.
• Body is the text in the email.
• Attachment is the path to the attachment file, where only one file is accepted. The reason for this is that the parameter 'Attachment' in the SendMail(…) method is of type String! You can circumvent this restriction by, for example, packing all attachments into an archive.

The specification of an (active) e-mail address (TO) is mandatory. All other arguments are optional. It is sufficient if you provide the necessary and optional parameters internally in your Gambas programme or enter the data with a form:

Figure 24.4.2.1.1: GUI: SMTP client

After sending the email, the data is transferred to the system's standard email client. The following notes refer to the email client Thunderbird:

• The attachment is transferred and displayed correctly. Attention: Not all e-mail clients transfer the attachment correctly.
• You can only select one file as an attachment in the programme.
• The recipient lists are not transferred to the email client as a comma-separated list, but in separate, individual lines!
• It has been shown that only one recipient from each of the CC and BCC lists is entered correctly. All others appear as normal recipients.

I think this is because the console programme xdg-email is used internally to send an email to the preferred email client. In the xdg-email programme, a fine distinction is made between several addresses for TO and one address each for CC and BCC.

xdg-email [--utf8] [--cc address] [--bcc address] [--subject text] [--body text ] [--attach file]
          [ mailto-uri | address(es) ]

Figure 24.4.2.1.2: Standard e-mail programme in the system with the transferred data

The source code appears to be very extensive - but this is deceptive because extensive checks on the captured arguments for the Desktop.SendMail(…) method are intended to ensure that only valid data is passed:

' Gambas class file
 
Private sEMailAnhangPfad As String
 
Public Sub Form_Open()
  SetFormPropertys
End ' Form_Open()
 
Public Sub btnAddAttachment_Click()
 
' Es wird nur ein Anhang akzeptiert, denn der Parameter Attachment in SendMail(...) ist vom Typ String!
  If lboxAttachments.Count = 1 Then
     lboxAttachments.Remove(0)
  Endif
  Dialog.Title = "EMail-Anhang-Auswahl-Dialog"
  Dialog.Path = User.Home
  If Dialog.OpenFile() Then Return
  HSplit1.Layout = [75, 25]
  sEMailAnhangPfad = Dialog.Path
  lboxAttachments.Add(" " & File.Name(sEMailAnhangPfad))
  lboxAttachments.Index = lboxAttachments.Count - 1
 
End ' btnAddAttachment_Click()
 
Public Sub btnEMailToDesktopClient_Click()
  Dim sToList, sCCList, sBCCList, sSubject, sEMailBody As String
  Dim sAttachment, sMessage, sEMPattern, sElement As String
  Dim aSendTo1, aSendCC1, aSendBCC1 As New String[]
  Dim aSendTo, aSendCC, aSendBCC As New String[]
 
  sEMPattern = "^[\\w-]+(?:\\.[\\w-]+)*@(?:[\\w-]+\\.)+[a-zA-Z]{2,7}$" ' Muster zur Syntax-Prüfung
' sEMPattern = "^[a-zA-Z0-9._+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,7}$"
' ----------------------------------------------------------------------
 
' EMail-Adressen der Empfänger festlegen (mindestens eine EMail-Adresse )
  aSendTo1 = New String[]
  If txbTo.Text Then
     sToList = Replace(txbTo.Text, Chr(32), "")
     If InStr(sToList, ",") Then
        aSendTo1 = Split(sToList, ",")
     Else
        aSendTo1.Add(sToList)
     Endif ' InStr(sToList, ",") ?
  Else
     Message.Warning("Die EMail hat keinen Empfänger!")
     txbTo.SetFocus
     Return
  Endif ' txbTo.Text ?
 
  aSendTo = New String[]
  For Each sElement In aSendTo1
    If sElement Match sEMPattern Then
       aSendTo.Add(sElement)
    Else
       sMessage = Message.Warning("Mindestens eine Empfänger-EMail-Adresse ist nicht korrekt!")
       txbTo.SetFocus
       Return
    Endif
  Next
' ----------------------------------------------------------------------------
' Option: Zusätzliche EMail-Adressen der Empfänger festlegen - CC (CarbonCopy)
  aSendCC1 = New String[]
  If txbCC.Text Then
     sCCList = Replace(txbCC.Text, Chr(32), "")
     If InStr(sCCList, ",") Then
        aSendCC1.Add(Split(sCCList, ",")[0]) ' Nur die erste Adresse wird übernommen
     Else
        aSendCC1.Add(sCCList)
     Endif ' InStr(sCCList, ",") ?
 
     aSendCC = New String[]
     For Each sElement In aSendCC1
       If sElement Match sEMPattern Then
          aSendCC.Add(sElement)
       Else
          sMessage = "Mindestens eine CC-Empfänger-EMail-Adresse<br>(CarbonCopy) ist nicht korrekt!"
          Message.Warning(sMessage)
          txbCC.SetFocus
          Return
       Endif
     Next
  Endif ' txbCC.Text ?
' ----------------------------------------------------------------------------------------------
' Option: Zusätzliche, versteckte EMail-Adressen der Empfänger festlegen - BCC (BlindCarbonCopy)
  aSendBCC1 = New String[]
  If txbBCC.Text Then
     sBCCList = Replace(txbBCC.Text, Chr(32), "")
     If InStr(sBCCList, ",") Then
        aSendBCC1.Add(Split(sBCCList, ",")[0]) ' Nur die erste Adresse wird übernommen
     Else
        aSendBCC1.Add(sBCCList)
     Endif ' InStr(sBCCList, ",")
 
     For Each sElement In aSendBCC1
       If sElement Match sEMPattern Then
          aSendBCC.Add(sElement)
       Else
          sMessage = "Mindestens eine BCC-Empfänger-EMail-Adresse<br>(BlindCarbonCopy) ist nicht korrekt!"
          Message.Warning(sMessage)
          txbBCC.SetFocus
          Return
       Endif
     Next
  Endif ' txbBCC.Text ?
' --------------------------------------------------------------------
  If txbSubject.Text Then
     sSubject = txbSubject.Text
  Else
     Message.Warning("Die EMail hat keinen Betreff!")
     txbSubject.SetFocus
     Return
  Endif ' txtSubject.Text ?
' --------------------------------------------------------------------
  If txaMailBody.Text Then
     sEMailBody = txaMailBody.Text
  Else
     Message.Warning("Die EMail enthält keine Nachricht!")
     txaMailBody.SetFocus
     Return
  Endif ' txaMailBody ?
 
' ---------------------------------
  sAttachment = sEMailAnhangPfad
' ---------------------------------
 
  Try Desktop.SendMail(aSendTo, aSendCC, aSendBCC, sSubject, sEMailBody, sAttachment)
  If Error Then
     sMessage = "Fehler bei der Übergabe der EMail"
     sMessage &= gb.NewLine & "an das Desktop-Standard-EMail-Programm!"
     sMessage &= gb.NewLine & "Fehler-Text: " & Error.Text
     Message.Error(sMessage)
  Endif
 
End ' btnEMailToClient_Click()
 
Private Sub SetFormPropertys()
  FMain.Center
  FMain.Arrangement = Arrange.Vertical
  FMain.Expand = False
  FMain.Margin = True
  FMain.Spacing = True
  FMain.Utility = True
 
' Container HSplit
  HSplit1.Layout = [100, 0] ' Man sieht nach dem Programmstart die Box für die Anhänge zunächst nicht
 
' Container VBox links im Container HSplit
  vboxLeft.Margin = True ' Fester Abstand zwischen VBox-Rand und den 4 inneren HBoxen
  vboxLeft.Spacing = True ' Fester Abstand zwischen den 4 inneren HBoxen
 
  hboxTo.Spacing = True ' Fester Abstand zwischen TextLabel und TextBox in der HBox (Empfänger)
  txlTo.W = 168 ' Feste Breite des TextLabels → Gilt für alle 4 TextLabel
  txlTo.Alignment = Align.Right ' Text-Ausrichtung auf dem TextLabel ist "rechts"
  txbTo.Expand = True ' Die Weite der Textbox passt sich dynamisch an die Container-Weite an
 
  hboxCC.Spacing = True
  txlCC.W = 168
  txlCC.Alignment = Align.Right
  txbCC.Expand = True
 
  hboxBCC.Spacing = True
  txlBCC.W = 168
  txlBCC.Alignment = Align.Right
  txbBCC.Expand = True
 
  hboxSubject.Spacing = True
  lblSubject.W = 168
  lblSubject.Alignment = Align.Right
  txbSubject.Expand = True
 
' Container rechts im Container HSplit
' panAttachment ist ein Panel mit spezifischen Eigenschaftswerten (ohne Rand, Anordnung vertikal)
  panAttachment.Border = Border.None ' Panel ohne Rand
  panAttachment.Arrangement = Arrange.Vertical ' Vertikale Anordnung der 2 inneren HBoxen
  panAttachment.Margin = True ' Fester Abstand zwischenPanel und den zwei inneren HBoxen
  panAttachment.Spacing = True ' Fester (vertikaler) Abstand zwischen den zwei inneren HBoxen
 
  lblAttachment.Alignment = Align.TopLeft ' Textanzeige in der linken, oberen Ecke
  hboxLIstBox.Expand = True ' Maximale Ausdehnung
  lboxAttachments.Expand = True ' Maximale Ausdehnung
  lboxAttachments.ScrollBar = Scroll.Vertical
  lboxAttachments.Mode = Select.Single
 
' Steuerelement TextArea
  MailBody.Expand = True ' Füllt automatisch die Fläche, die HSplit und HBox (unten) frei lassen
 
' Container HBox unten
  hboxBottom.Height = 24
  hboxBottom.Margin = False
  hboxBottom.Spacing = True
  panSpace.Expand = True ' Schiebt die 2 Button an den linken bzw. an den rechten Rand des Containers
 
  btnEMailToDesktopClient.Text = "  EMail an das Desktop-Standard-EMail-Programm schicken"
 
  txbTo.Clear
  txbCC.Clear
  txbBCC.Clear
  txbSubject.Clear
  txaMailBody.Clear
  txaMailBody.Wrap = True
End ' SetFormPropertys