« Back to index

Connectivity

Table of Contents:

• ActivityStarter
• BluetoothClient
• BluetoothServer
• Serial
• Web

ActivityStarter

A component that can launch an activity using the StartActivity method.

Activities that can be launched include:

• Starting another App Inventor for Android app. To do so, first find out the class of the other application by downloading the source code and using a file explorer or unzip utility to find a file named “youngandroidproject/project.properties”. The first line of the file will start with “main=” and be followed by the class name; for example, main=com.gmail.Bitdiddle.Ben.HelloPurr.Screen1. (The first components indicate that it was created by Ben.Bitdiddle@gmail.com.) To make your ActivityStarter launch this application, set the following properties:
  • ActivityPackage to the class name, dropping the last component (for example, com.gmail.Bitdiddle.Ben.HelloPurr)
  • ActivityClass to the entire class name (for example, com.gmail.Bitdiddle.Ben.HelloPurr.Screen1)
• Starting the camera application by setting the following properties:
  • Action: android.intent.action.MAIN
  • ActivityPackage: com.android.camera
  • ActivityClass: com.android.camera.Camera
• Performing web search. Assuming the term you want to search for is “vampire” (feel free to substitute your own choice), set the properties to:
  • Action: android.intent.action.WEB_SEARCH
  • ExtraKey: query
  • ExtraValue: vampire
  • ActivityPackage: com.google.android.providers.enhancedgooglesearch
  • ActivityClass: com.google.android.providers.enhancedgooglesearch.Launcher
• Opening a browser to a specified web page. Assuming the page you want to go to is “www.facebook.com” (feel free to substitute your own choice), set the properties to:
  • Action: android.intent.action.VIEW
  • DataUri: http://www.facebook.com

Properties

Action

Specifies the action that will be used to start the activity.

ActivityClass

Specifies the class part of the specific component that will be started.

ActivityPackage

Specifies the package part of the specific component that will be started.

DataType

Specifies the MIME type to pass to the activity.

DataUri

Specifies the data URI that will be used to start the activity.

ExtraKey

Specifies the extra key that will be passed to the activity. Obsolete. Should use Extras instead

ExtraValue

Specifies the extra value that will be passed to the activity. Obsolete. Should use Extras instead

Extras

Returns the list of key-value pairs that will be passed as extra data to the activity.

Result

Returns the result from the activity.

ResultName

Specifies the name that will be used to retrieve a result from the activity.

ResultType

Returns the MIME type from the activity.

ResultUri

Returns the URI from the activity.

Events

ActivityCanceled()

Event raised if this `ActivityStarter returns because the activity was canceled.

AfterActivity(result)

Event raised after this ActivityStarter returns.

Methods

ResolveActivity()

Returns the name of the activity that corresponds to this ActivityStarter, or an empty string if no corresponding activity can be found.

StartActivity()

Start the activity corresponding to this ActivityStarter.

BluetoothClient

Use BluetoothClient to connect your device to other devices using Bluetooth. This component uses the Serial Port Profile (SPP) for communication. If you are interested in using Bluetooth low energy, please see the BluetoothLE extension.

Properties

AddressesAndNames

Returns the list of paired Bluetooth devices. Each element of the returned list is a String consisting of the device’s address, a space, and the device’s name. On Android 12 or later, if the permissions BLUETOOTH_CONNECT and BLUETOOTH_SCAN have not been granted to the app, the block will raise an error via the Screen’s PermissionDenied event.

Available

Returns true if Bluetooth is available on the device, false otherwise.

CharacterEncoding

Returns the character encoding to use when sending and receiving text.

DelimiterByte

Returns the delimiter byte to use when passing a negative number for the numberOfBytes parameter when calling ReceiveText, ReceiveSignedBytes, or ReceiveUnsignedBytes.

DisconnectOnError

Specifies whether BluetoothClient should be disconnected automatically when an error occurs.

Enabled

Returns true if Bluetooth is enabled, false otherwise.

HighByteFirst

Specifies whether numbers are sent and received with the most significant byte first.

IsConnected

Returns true if a connection to a Bluetooth device has been made.

NoLocationNeeded

On Android 12 and later, indicates that Bluetooth is not used to determine the user’s location.

PollingRate

Returns the configured polling rate value of the Bluetooth Client.

Secure

Specifies whether a secure connection should be used.

Events

None

Methods

BytesAvailableToReceive()

Returns number of bytes available from the input stream.

Connect(address)

Connect to a Bluetooth device with the given address.

ConnectWithUUID(address,uuid)

Connect to a Bluetooth device with the given address and a specific UUID.

Disconnect()

Disconnects from the connected Bluetooth device.

IsDevicePaired(address)

Checks whether the Bluetooth device with the given address is paired.

ReceiveSigned1ByteNumber()

Reads a signed 1-byte number.

ReceiveSigned2ByteNumber()

Reads a signed 2-byte number.

ReceiveSigned4ByteNumber()

Reads a signed 4-byte number.

ReceiveSignedBytes(numberOfBytes)

Reads a number of signed bytes from the input stream and returns them as a List.

If numberOfBytes is negative, this method reads until a delimiter byte value is read. The delimiter byte value is included in the returned list.

ReceiveText(numberOfBytes)

Reads a number of bytes from the input stream and converts them to text.

If numberOfBytes is negative, read until a delimiter byte value is read.

ReceiveUnsigned1ByteNumber()

Reads an unsigned 1-byte number.

ReceiveUnsigned2ByteNumber()

Reads an unsigned 2-byte number.

ReceiveUnsigned4ByteNumber()

Reads an unsigned 4-byte number.

ReceiveUnsignedBytes(numberOfBytes)

Reads a number of unsigned bytes from the input stream and returns them as a List.

If numberOfBytes is negative, this method reads until a delimiter byte value is read. The delimiter byte value is included in the returned list.

Send1ByteNumber(number)

Decodes the given number String to an integer and writes it as one byte to the output stream.

If the number could not be decoded to an integer, or the integer would not fit in one byte, then the Form’s ErrorOccurred event is triggered and this method returns without writing any bytes to the output stream.

Send2ByteNumber(number)

Decodes the given number String to an integer and writes it as two bytes to the output stream.

If the number could not be decoded to an integer, or the integer would not fit in two bytes, then the Form’s ErrorOccurred event is triggered and this method returns without writing any bytes to the output stream.

Send4ByteNumber(number)

Decodes the given number String to an integer and writes it as four bytes to the output stream.

If the number could not be decoded to an integer, or the integer would not fit in four bytes, then the Form’s ErrorOccurred event is triggered and this method returns without writing any bytes to the output stream.

SendBytes(list)

Takes each element from the given list, converts it to a String, decodes the String to an integer, and writes it as one byte to the output stream.

If an element could not be decoded to an integer, or the integer would not fit in one byte, then the Form’s ErrorOccurred event is triggered and this method returns without writing any bytes to the output stream.

SendText(text)

Converts the given text to bytes and writes them to the output stream.

BluetoothServer

Use the BluetoothServer component to turn your device into a server that receive connections from other apps that use the BluetoothClient component.

Properties

Available

Returns true if Bluetooth is available on the device, false otherwise.

CharacterEncoding

Returns the character encoding to use when sending and receiving text.

DelimiterByte

Returns the delimiter byte to use when passing a negative number for the numberOfBytes parameter when calling ReceiveText, ReceiveSignedBytes, or ReceiveUnsignedBytes.

Enabled

Returns true if Bluetooth is enabled, false otherwise.

HighByteFirst

Specifies whether numbers are sent and received with the most significant byte first.

IsAccepting

Returns true if this BluetoothServer component is accepting an incoming connection.

IsConnected

Returns true if a connection to a Bluetooth device has been made.

Secure

Specifies whether a secure connection should be used.

Events

ConnectionAccepted()

Indicates that a bluetooth connection has been accepted.

Methods

AcceptConnection(serviceName)

Accept an incoming connection with the Serial Port Profile (SPP).

AcceptConnectionWithUUID(serviceName,uuid)

Accept an incoming connection with a specific UUID.

BytesAvailableToReceive()

Returns number of bytes available from the input stream.

Disconnect()

Disconnects from the connected Bluetooth device.

ReceiveSigned1ByteNumber()

Reads a signed 1-byte number.

ReceiveSigned2ByteNumber()

Reads a signed 2-byte number.

ReceiveSigned4ByteNumber()

Reads a signed 4-byte number.

ReceiveSignedBytes(numberOfBytes)

Reads a number of signed bytes from the input stream and returns them as a List.

If numberOfBytes is negative, this method reads until a delimiter byte value is read. The delimiter byte value is included in the returned list.

ReceiveText(numberOfBytes)

Reads a number of bytes from the input stream and converts them to text.

If numberOfBytes is negative, read until a delimiter byte value is read.

ReceiveUnsigned1ByteNumber()

Reads an unsigned 1-byte number.

ReceiveUnsigned2ByteNumber()

Reads an unsigned 2-byte number.

ReceiveUnsigned4ByteNumber()

Reads an unsigned 4-byte number.

ReceiveUnsignedBytes(numberOfBytes)

Reads a number of unsigned bytes from the input stream and returns them as a List.

If numberOfBytes is negative, this method reads until a delimiter byte value is read. The delimiter byte value is included in the returned list.

Send1ByteNumber(number)

Decodes the given number String to an integer and writes it as one byte to the output stream.

If the number could not be decoded to an integer, or the integer would not fit in one byte, then the Form’s ErrorOccurred event is triggered and this method returns without writing any bytes to the output stream.

Send2ByteNumber(number)

Decodes the given number String to an integer and writes it as two bytes to the output stream.

If the number could not be decoded to an integer, or the integer would not fit in two bytes, then the Form’s ErrorOccurred event is triggered and this method returns without writing any bytes to the output stream.

Send4ByteNumber(number)

Decodes the given number String to an integer and writes it as four bytes to the output stream.

If the number could not be decoded to an integer, or the integer would not fit in four bytes, then the Form’s ErrorOccurred event is triggered and this method returns without writing any bytes to the output stream.

SendBytes(list)

Takes each element from the given list, converts it to a String, decodes the String to an integer, and writes it as one byte to the output stream.

If an element could not be decoded to an integer, or the integer would not fit in one byte, then the Form’s ErrorOccurred event is triggered and this method returns without writing any bytes to the output stream.

SendText(text)

Converts the given text to bytes and writes them to the output stream.

StopAccepting()

Stop accepting an incoming connection.

Serial

Component for Serial

Properties

BaudRate

Returns the current baud rate

BufferSize

Returns the buffer size in bytes

IsInitialized

Returns true when the Serial has been initialized.

IsOpen

Returns true when the Serial connection is open.

Events

None

Methods

CloseSerial()

Closes serial connection. Returns true when closed.

InitializeSerial()

Initializes serial connection.

OpenSerial()

Opens serial connection. Returns true when opened.

PrintSerial(data)

Writes given data to serial, and appends a new line at the end.

ReadSerial()

Reads data from serial.

WriteSerial(data)

Writes given data to serial.

Web

Non-visible component that provides functions for HTTP GET, POST, PUT, and DELETE requests.

Properties

AllowCookies

Specifies whether cookies should be allowed

RequestHeaders

Sets the request headers.

ResponseFileName

Specifies the name of the file where the response should be saved. If SaveResponse is true and ResponseFileName is empty, then a new file name will be generated.

ResponseTextEncoding

Specifies the Response Text Encoding.

SaveResponse

Specifies whether the response should be saved in a file.

Timeout

Returns the number of milliseconds that each request will wait for a response before they time out. If set to 0, then the request will wait for a response indefinitely.

Url

Specifies the URL.

Events

GotFile(url,responseCode,responseType,fileName)

Event indicating that a request has finished.

GotText(url,responseCode,responseType,responseContent)

Event indicating that a request has finished.

TimedOut(url)

Event indicating that a request has timed out.

Methods

BuildRequestData(list)

Converts a list of two-element sublists, representing name and value pairs, to a string formatted as application/x-www-form-urlencoded media type, suitable to pass to PostText.

ClearCookies()

Clears all cookies for this Web component.

Delete()

Performs an HTTP DELETE request using the Url property and retrieves the response.

If the SaveResponse property is true, the response will be saved in a file and the GotFile event will be triggered. The ResponseFileName property can be used to specify the name of the file.

If the SaveResponse property is false, the GotText event will be triggered.

Get()

Performs an HTTP GET request using the Url property and retrieves the response.

If the SaveResponse property is true, the response will be saved in a file and the GotFile event will be triggered. The ResponseFileName property can be used to specify the name of the file.

If the SaveResponse property is false, the GotText event will be triggered.

HtmlTextDecode(htmlText)

Decodes the given HTML text value.

HTML Character Entities such as &, <, >, ', and " are changed to &, <, >, ', and ". Entities such as &#xhhhh;, and &#nnnn; are changed to the appropriate characters.

JsonObjectEncode(jsonObject)

Returns the value of a built-in type (i.e., boolean, number, text, list, dictionary) in its JavaScript Object Notation representation. If the value cannot be represented as JSON, the Screen’s ErrorOccurred event will be run, if any, and the Web component will return the empty string.

JsonTextDecode(jsonText)

Decodes the given JSON encoded value to produce a corresponding AppInventor value. A JSON list [x, y, z] decodes to a list (x y z), A JSON object with key A and value B, (denoted as {A:B}) decodes to a list ((A B)), that is, a list containing the two-element list (A B).

Use the method JsonTextDecodeWithDictionaries if you would prefer to get back dictionary objects rather than lists-of-lists in the result.

JsonTextDecodeWithDictionaries(jsonText)

Decodes the given JSON encoded value to produce a corresponding App Inventor value. A JSON list [x, y, z] decodes to a list (x y z). A JSON Object with name A and value B, denoted as {a: b} decodes to a dictionary with the key a and value b.

PatchFile(path)

Performs an HTTP PATCH request using the Url property and data from the specified file.

If the SaveResponse property is true, the response will be saved in a file and the GotFile event will be triggered. The ResponseFileName property can be used to specify the name of the file.

If the SaveResponse property is false, the GotText event will be triggered.

PatchText(text)

Performs an HTTP PATCH request using the Url property and the specified text.

The characters of the text are encoded using UTF-8 encoding.

If the SaveResponse property is true, the response will be saved in a file and the GotFile event will be triggered. The responseFileName property can be used to specify the name of the file.

If the SaveResponse property is false, the GotText event will be triggered.

PatchTextWithEncoding(text,encoding)

Performs an HTTP PATCH request using the Url property and the specified text.

The characters of the text are encoded using the given encoding.

If the SaveResponse property is true, the response will be saved in a file and the GotFile event will be triggered. The ResponseFileName property can be used to specify the name of the file.

If the SaveResponse property is false, the GotText event will be triggered.

PostFile(path)

Performs an HTTP POST request using the Url property and data from the specified file.

If the SaveResponse property is true, the response will be saved in a file and the GotFile event will be triggered. The ResponseFileName property can be used to specify the name of the file.

If the SaveResponse property is false, the GotText event will be triggered.

PostText(text)

Performs an HTTP POST request using the Url property and the specified text.

The characters of the text are encoded using UTF-8 encoding.

If the SaveResponse property is true, the response will be saved in a file and the GotFile event will be triggered. The responseFileName property can be used to specify the name of the file.

If the SaveResponse property is false, the GotText event will be triggered.

PostTextWithEncoding(text,encoding)

Performs an HTTP POST request using the Url property and the specified text.

The characters of the text are encoded using the given encoding.

If the SaveResponse property is true, the response will be saved in a file and the GotFile event will be triggered. The ResponseFileName property can be used to specify the name of the file.

If the SaveResponse property is false, the GotText event will be triggered.

PutFile(path)

Performs an HTTP PUT request using the Url property and data from the specified file.

If the SaveResponse property is true, the response will be saved in a file and the GotFile event will be triggered. The ResponseFileName property can be used to specify the name of the file.

If the SaveResponse property is false, the GotText event will be triggered.

PutText(text)

Performs an HTTP PUT request using the Url property and the specified text.

The characters of the text are encoded using UTF-8 encoding.

If the SaveResponse property is true, the response will be saved in a file and the GotFile event will be triggered. The responseFileName property can be used to specify the name of the file.

If the SaveResponse property is false, the GotText event will be triggered.

PutTextWithEncoding(text,encoding)

Performs an HTTP PUT request using the Url property and the specified text.

The characters of the text are encoded using the given encoding.

If the SaveResponse property is true, the response will be saved in a file and the GotFile event will be triggered. The ResponseFileName property can be used to specify the name of the file.

If the SaveResponse property is false, the GotText event will be triggered.

UriDecode(text)

Decodes the encoded text value so that the values aren’t URL encoded anymore.

UriEncode(text)

Encodes the given text value so that it can be used in a URL.

XMLTextDecode(XmlText)

Decodes the given XML string to produce a list structure. <tag>string</tag> decodes to a list that contains a pair of tag and string. More generally, if obj1, obj2, … are tag-delimited XML strings, then <tag>obj1 obj2 ...</tag> decodes to a list that contains a pair whose first element is tag and whose second element is the list of the decoded obj’s, ordered alphabetically by tags.

Examples:

• <foo><123/foo> decodes to a one-item list containing the pair (foo 123)
• <foo>1 2 3</foo> decodes to a one-item list containing the pair (foo "1 2 3")
• <a><foo>1 2 3</foo><bar>456</bar></a> decodes to a list containing the pair (a X) where X is a 2-item list that contains the pair (bar 123) and the pair (foo "1 2 3").

If the sequence of obj’s mixes tag-delimited and non-tag-delimited items, then the non-tag-delimited items are pulled out of the sequence and wrapped with a “content” tag. For example, decoding <a><bar>456</bar>many<foo>1 2 3</foo>apples<a></code> is similar to above, except that the list X is a 3-item list that contains the additional pair whose first item is the string “content”, and whose second item is the list (many, apples). This method signals an error and returns the empty list if the result is not well-formed XML.

XMLTextDecodeAsDictionary(XmlText)

Decodes the given XML string to produce a dictionary structure. The dictionary includes the special keys $tag, $localName, $namespace, $namespaceUri, $attributes, and $content, as well as a key for each unique tag for every node, which points to a list of elements of the same structure as described here.

The $tag key is the full tag name, e.g., foo:bar. The $localName is the local portion of the name (everything after the colon : character). If a namespace is given (everything before the colon : character), it is provided in $namespace and the corresponding URI is given in $namespaceUri. The attributes are stored in a dictionary in $attributes and the child nodes are given as a list under $content.

More Information on Special Keys

Consider the following XML document:

   <ex:Book xmlns:ex="http://example.com/">
     <ex:title xml:lang="en">On the Origin of Species</ex:title>
     <ex:author>Charles Darwin</ex:author>
   </ex:Book>

When parsed, the $tag key will be "ex:Book", the $localName key will be "Book", the $namespace key will be "ex", $namespaceUri will be "http://example.com/", the $attributes key will be a dictionary {} (xmlns is removed for the namespace), and the $content will be a list of two items representing the decoded <ex:title> and <ex:author> elements. The first item, which corresponds to the <ex:title> element, will have an $attributes key containing the dictionary {"xml:lang": "en"}. For each name=value attribute on an element, a key-value pair mapping name to value will exist in the $attributes dictionary. In addition to these special keys, there will also be "ex:title" and "ex:author" to allow lookups faster than having to traverse the $content list.