Telecom
| Manual contents (Statement index) | |
|---|---|
| Language features | The basics • Arrays • Data structures • Interrupt routines • User-defined functions |
| Interfaces | Audio player • Bluetooth • Files • Graphics • HTML • Keyboard • Sockets • SQL • Telecom |
| Programming notes | Coexisting with Android |
Programs that run under RFO-BASIC! can telecommunicate by managing connections in the following services:
- The cell telephone
- Texts using the Simple Message Service (SMS)
The first two types of statement might not be available. The prerequisites are as follows:
- The Android device must be a cell phone with a working connection to a cellular network.
- Operation of the cell phone and of SMS requires Android permissions. The user is asked to grant RFO-BASIC! these permissions after installing RFO-BASIC!. The user is free not to grant the permissions.
- The SMS statements are not available in RFO-BASIC! versions 1.92gp nor 1.92.1 (see the Main Page), because the Google Play Store no longer hosts applications that can send SMS messages.
Cell telephone[edit]
RFO-BASIC! statements let a program send a phone number to the dialer app and detect an incoming call, subject to the prerequisites listed in this article's Introduction. They do not let a BASIC program conduct a call, such as with text-to-speech and speech-to-text. You can write a custom phone dialer or a program that alerts the user that a call is arriving. Usually, the user would then use the phone app shipped with the device.
MYPHONENUMBER[edit]
Determine the device's phone number
- Synopsis
MYPHONENUMBER <phonenum_svar>
- Description
The MYPHONENUMBER statement returns in <phonenum_svar> the phone number of the Android device.
The context of this phone number is device-specific. Typically, it is the complete set of digits that one would use to telephone the device. For example, in devices configured for the TracFone service that covers the United States, the phone number includes the area code (which specifies all or part of a state) but does not include the country code that specifies the United States.
It is not a run-time error if the device is not a telephone or is not connected to a cellular network. The statement sets <phonenum_svar> to the following string value:
Get phone number failed.
Dialing the phone[edit]
Place a phone call
- Synopsis
PHONE.CALL <numbertocall_sexp> PHONE.DIAL <numbertocall_sexp>
- Description
These two statements place a phone call. The number to call is in the string expression. The digits of this string must include the exact digits to dial, including access code, country code, area code, and so on.
The PHONE.CALL statement dials the phone directly. The BASIC program would next monitor the state of the phone, using the statements described in the next section.
The PHONE.DIAL statement feeds the phone number to the device's dialer app. The dialer app is opened and gets control of the Android screen. If someone picks up the phone on the other end, the local user can have a conversation using the dialer app. When the call is complete, BASIC regains control of the Android screen.
If <numbertocall_sexp> contains letters, they are converted to numbers according to the keytop legends on American phones:
| Letters | Converted to |
|---|---|
| A B C | 2 |
| D E F | 3 |
| G H I | 4 |
| J K L | 5 |
| M N O | 6 |
| P Q R S | 7 |
| T U V | 8 |
| W X Y Z | 9 |
Detecting phone state[edit]
- Synopsis
PHONE.RCV.INIT PHONE.RCV.NEXT <state_nvar>, <phonenum_svar>
- Description
The cell phone can be in one of three states: Idle (0), ringing (1), and call-in-progress (2).
To monitor the phone state, the RFO-BASIC! program uses the PHONE.RCV.INIT statement. This starts a listener task that detects changes in the phone state. The listener task remains active until the program exits.
Assuming the listener task is operating, the RFO-BASIC! program uses the PHONE.RCV.NEXT statement. It returns in <state_nvar> one of three values according to the phone state:
| <state_nvar> | Meaning | Additional information |
|---|---|---|
| 0 | Idle | The statement sets <phonenum_svar> to the empty string. |
| 1 | Ringing | (Applies only to outgoing calls initiated by PHONE.CALL or PHONE.DIAL.) The statement sets <phonenum_svar> to the string the BASIC program passed to PHONE.CALL or PHONE.DIAL. |
| 2 | Call in Progress | For outgoing calls, the statement sets <phonenum_svar> to the empty string. For incoming calls, the statement sets <phonenum_svar> to the phone number of the caller. |
SMS messaging[edit]
RFO-BASIC! statements let a program send and receive SMS texts, subject to the prerequisites listed in this article's Introduction.
SMS.SEND[edit]
Send a text
- Synopsis
SMS.SEND <numbertocall_sexp>, <message_sexp>
- Description
The SMS.SEND statement sends a text with <message_sexp> to the phone number specified in <numbertocall_sexp>. The digits of this string must include the exact digits to dial, including access code, country code, area code, and so on. If <numbertocall_sexp> contains letters, they are converted to numbers in the same way as for Dialing the phone above.
Receive texts[edit]
- Synopsis
SMS.RCV.INIT SMS.RCV.NEXT <message_svar>
- Description
Comparably to Detecting phone state above, to monitor incoming texts, the RFO-BASIC! program uses the SMS.RCV.INIT statement. This starts a listener task that detects incoming texts. The listener task remains active until the program exits.
Assuming the listener task is operating, the RFO-BASIC! program uses the SMS.RCV.NEXT statement. This statement returns a result in <message_svar>:
- If one or more SMS messages have arrived at the phone, the result is the first text in the queue not already returned to the program. Subsequent calls to SMS.RCV.NEXT will return different texts.
- If there is no SMS message in the queue, the result is "
@".
- Example
This simple example loops forever, receiving texts and displaying them on the Text Console:
SMS.RCV.INIT % Start the SMS listener DO % Loop forever DO % Inner loop until a text is received PAUSE 5000 % Wait 5 seconds SMS.RCV.NEXT m$ % Poll for a new text UNTIL m$ <> "@" % Until something other than the no-message indication PRINT m$ % Print it on the Text Console UNTIL 0 % Then go get another, forever
Email[edit]
An Android device can use RFO-BASIC! to send emails. It is not necessary that the Android device be a cell phone, nor that it have access to a cell network. If there is a cell network, emails can be sent using mobile data. If not, emails can be sent over WiFi or Bluetooth.
The Android device must have an email app that has information on an email account. This app will have been informed of the email provider to use, and will have the device user's email address, displayed address, and password to use the email provider.
EMAIL.SEND[edit]
Send an email
- Synopsis
EMAIL.SEND <recipient_sexp>, <subject_sexp>, <body_sexp>
- Description
The EMAIL.SEND statement prepares to send one email. The mandatory parameter <recipient_sexp> describes the recipient to whom to send the email; this is an email address in the usual format using @. If the <subject_sexp> parameter is present, its text is the Subject: line of the email; otherwise, the email does not have a Subject: line. If the <body_sexp> parameter is present, its text is the body of the email; otherwise, the email has no content.
The EMAIL.SEND statement does not send the email but merely passes the information in its parameters to the email app. The email app is started, if it is not already active; it acquires the Android screen, and typically displays the information from the EMAIL.SEND parameters. The user is free to edit this as desired. A typical email app will let the user add recipients, Cc: and Bcc: recipients, edit the Subject: line or text of the message, actually send the email, or abort the transmission; this may save the message as a Draft for later editing, or may discard the email.
EMAIL.SEND returns a run-time error if there is no email app. If the email app exists but does not know an email account, the app typically does not display the information EMAIL.SEND passes to it; it may ask the user to specify an email account.
When the email app disposes of the email in any way, control returns to the RFO-BASIC! program, which recovers control of the Android screen. However, EMAIL.SEND does not return any information on whether the user decided to actually send the email, nor on whether the email was successfully sent.
Sources[edit]
- De Re BASIC! (v1.91), pages 130-131.