Skip to main content
AuthTask runs RunAuth on a worker thread. It resolves the best available server (LAN first, then WAN), posts credentials to /auth/{user}/{pass}, parses the JSON response, and signals success or a typed failure reason via the result and done output fields.
AuthTask uses TIMEOUT_AUTH (15 000 ms) for the credential HTTP request — longer than the default TIMEOUT_HTTP — to allow for slow LAN servers.

​
XML component definition

AuthTask.xml
<?xml version="1.0" encoding="utf-8" ?>
<component name="AuthTask" extends="Task">
  <interface>
    <!-- inputs -->
    <field id="username"      type="string"     value="" />
    <field id="password"      type="string"     value="" />
    <!-- outputs -->
    <field id="result"        type="assocarray" />
    <field id="done"          type="boolean"    value="false" />
    <field id="statusMessage" type="string"     value="" />
    <field id="statusTick"    type="integer"    value="0" />
  </interface>
  <task functionName="RunAuth" />
</component>

​
Input fields

​
username
String
The subscriber’s username. Leading and trailing whitespace is stripped before use. An empty value causes an immediate failure with errorMsg set.
​
password
String
The subscriber’s password. Trimmed the same way as username.

​
Output fields

​
result
AssocArray
Populated when done becomes true. Contains the fields listed in the Result object section below.
​
done
Boolean
Set to true once the task finishes, whether successful or not. Observe this field to know when result is ready.
​
statusMessage
String
Human-readable progress string updated throughout the task (e.g. "Conectando con servidor local...", "Validando credenciales..."). Suitable for display in the login screen.
​
statusTick
Integer
Monotonically incremented every time statusMessage changes. Observe this integer field to detect message updates even when the string value is identical.

​
Result object

The result assoc-array always contains these keys:
KeyTypeDescription
successBooleantrue when the user authenticated and the subscription is active
userIdStringSubscriber user ID returned by the server, or ""
streamUrlStringReserved; currently always ""
subscriberActiveBooleantrue when the subscription is in good standing
subscriberDisabledReasonStringHuman-readable reason from the server when the account is inactive
errorCodeIntegerOne of the AUTH_REASON_* constants (see Error codes)
authReasonIntegerAlias for errorCode; same value
errorMsgStringLocalised error string suitable for display
rawBodyStringRaw HTTP response body, useful for debugging
resolvedServerStringBase URL of the server that answered the request

​
Error codes

Defined in AppConstants.brs:
ConstantValueMeaning
AUTH_REASON_NONE0No error; authentication succeeded
AUTH_REASON_NETWORK_DOWN460Network unavailable or all servers timed out
AUTH_REASON_CREDENTIALS401Wrong username or password
AUTH_REASON_INACTIVE470Account exists but subscription is inactive
AUTH_REASON_PASSWORD_CHANGED471Session revoked because credentials were rotated

​
Function flow

1

Validate inputs

GTV_SafeTrim strips whitespace from username and password. If either is empty the task sets done = true immediately with an error result.
2

Check network

GTV_IsOnline() confirms a network interface is up. Failure sets errorCode = AUTH_REASON_NETWORK_DOWN.
3

Resolve server

GTV_ResolveServerForAuth() iterates GTV_ServerBuildAutoProbeList() — LAN entries first, then WAN — pinging each with GTV_PingServer(). The first reachable server is used. statusMessage is updated at each probe step.
4

POST credentials

Builds server + "/auth/" + encUser + "/" + encPass and calls GTV_HttpGet(authUrl, TIMEOUT_AUTH). The 15 s timeout gives LAN servers extra time to respond.
5

Classify HTTP failure

If the HTTP call fails, GTV_AuthClassifyFailure() maps the HTTP code and body to an AUTH_REASON_* constant and an appropriate errorMsg.
6

Parse subscriber status

Inspects subscriberStatus, subscriber_active, and active fields (in that order) to determine whether the account is enabled. A false value triggers a failure path that emits AUTH_REASON_INACTIVE or AUTH_REASON_PASSWORD_CHANGED.
7

Write global state

On success: sets m.global.activeServer, m.global.isAuthenticated = true, m.global.subscriberActive = true, and m.global.userId. Saves the resolved server via GTV_RegSaveLastServer().
8

Signal completion

Sets m.top.result and m.top.done = true.

​
AppConstants values used

ConstantValueUsed for
TIMEOUT_AUTH15000 msHTTP timeout for the credential request
TIMEOUT_HEALTH2500 msPing timeout inside GTV_PingServer()
SERVER_LAN_FORCE_RETRIES3Maximum LAN probe attempts before falling back to WAN
PATH_AUTH_TPL"/auth/{user}/{pass}"URL template for the auth endpoint
AUTH_REASON_*see table aboveTyped failure codes written to result.errorCode

​
Usage example

' Create and configure the task
authTask = CreateObject("roSGNode", "AuthTask")
authTask.username = m.top.usernameField.text
authTask.password = m.top.passwordField.text

' Observe the done flag on the main thread
authTask.observeFieldScoped("done", "OnAuthDone")
authTask.observeFieldScoped("statusMessage", "OnAuthStatus")

' Start the task
authTask.control = "RUN"

' --- callback ---
sub OnAuthDone()
    r = m.authTask.result
    if r.success
        ' navigate to main screen
    else
        ShowError(r.errorMsg)
    end if
end sub

sub OnAuthStatus()
    m.statusLabel.text = m.authTask.statusMessage
end sub
Do not read result until done is true. The assoc-array may be partially populated while the task is still running.

Build docs developers (and LLMs) love

Get started for freeTalk to us