Chapter 7—OW3 Worker Objects

You can build "low-level" Web- and Email-based communications into your Omnis applications using a number of different techniques or commands: this includes support for HTTP, SMTP, POP3, IMAP, and FTP communications and protocols; with the addition of JavaScript (Node.js), CRYPTO, HASH, and OAUTH2 in Studio 10, and LDAP and Python in Studio 11.

IMPORTANT: We recommend you use the OW3 Worker Objects (OW3) for all new development, since the older Web Worker Objects (OWEB) and the External commands are no longer supported.

The technique you choose to implement such support will depend on the breadth of support you require and the version of Omnis Studio you are using. The following techniques are available:

Example Apps

There is an example app for most of the OW3 Worker Objects available in the Samples group under the Hub in the Studio Browser to demonstrate the use of the OW3 Worker Objects; search for "worker" in the search box (in the window title bar/toolbar) under Samples in the Studio Browser. There are examples for: Crypto, FTP, Hash, HTTP, IMAP, POP3, SMTP, JS Worker, and LDAP.

Using the OW3 Workers

Using the OW3 Worker Objects you can execute a potentially long-running task on a background thread, such as running a large mailshot, that reports back to the main thread when the task is complete. Indeed, the OW3 workers allow you to execute multiple tasks simultaneously allowing you to increase the efficiency and workload of your app.

The OW3 worker objects use the open-source CURL library, and native secure connection implementations for Windows and macOS, so they should have fewer deployment issues than the implementations available in previous versions.

The web and email commands in any of the OW3 Workers are accessed via one of the Worker Objects available under the OW3 Worker Objects group in the Object Selection dialog in the Method Editor (do not use the Web Worker Objects group which contains the old OWEB worker objects). To use the web and email commands, you need to create an Object variable and set its subtype to one of the OW3 worker objects, such as HTTPClientWorker or FTPClientWorker, under the OW3 Worker Objects group. Alternatively, you can create an Object class and set its superclass to one of the OW3 worker objects, then create an Object variable or Object reference variable and set its subtype to the object class name. Having created the variable you can call the web or email commands (methods) using OBJECTVAR.$methodname.

All OW3 Worker Objects share the same base functionality, plus they have additional functions specific to their respective web or email protocol.

HTTP/2 support

From Studio 11, the OW3 Workers support HTTP/2 which is more secure than HTTP as it uses binary protocols instead of plaintext, and is generally faster and more efficient for web communication.

The nghttp2 open source library is included to accommodate HTTP/2 support, and various libraries have been updated including: zlib, mbedTLS, libssh2, and libcurl; if your application uses OW3 your product licensing should include the appropriate third-party licensing.

Base Worker Properties

All OW3 worker objects have the following properties:

Request Completion

The $alwaysfinish property allows asynchronous requests to continue to completion after the instance containing the OW3 object destructs; the property only applies to the HTTP, IMAP, SMTP, POP3 and FTP workers.

When the instance containing an OW3 worker closes, and the OW3 worker is executing via a call to $start(), the worker thread continues executing until completion in the background: in this case, no notifications will be generated, as there is not a suitable instance to receive them.

Note that even if $alwaysfinish is true, if you shut down Omnis before the request has completed, OW3 will cancel the request so that shutdown works correctly.

Base Worker Constants

Protocol Logging

OW3 worker objects can all use these constants to control protocol logging. Sum the constants to select the desired logging.

Base Worker Methods

All OW3 worker objects have the methods described in this section. There are normal methods that you call, and callback methods that you override to receive a notification.

Normal methods

$run

The $run method runs the worker on the main thread. Returns true if the worker executed successfully. The callback $completed will be called with the results of the request.

$start

The $start method runs the worker on a background thread; can be called multiple times to run different threads simultaneously to perform different tasks at the same time. Returns true if the worker was successfully started. The callback $completed will be called with the results of the request, or alternatively $cancelled will be called if the request is cancelled.

$cancel

The $cancel method cancels execution of worker on a background thread. Will not return until the request has been cancelled.

$getsecureoptions

The $getsecureoptions method gets the options that affect how secure connections are established.

OW3.$getsecureoptions([&bVerifyPeer,&bVerifyHost,&cCertFile,&cPrivKeyFile,&cPrivKeyPassword])

Returns Boolean true for success, or returns false and sets $errorcode and $errortext if an error occurs.

The parameters are:

$setsecureoptions

The $setsecureoptions method sets the options that affect how secure connections are established (call $setsecureoptions before calling $run or $start).

OW3.$setsecureoptions([bVerifyPeer=kTrue,bVerifyHost=kTrue,cCertFile='',cPrivKeyFile='',cPrivKeyPassword=''])

Returns Boolean true for success, or returns false and sets $errorcode and $errortext if an error occurs.

The parameters are:

$parserfc3339

The $parserfc3339() static method returns an Omnis date-time value from a RFC3339 formatted time.

OW3.$parserfc3339(cRfc3339[,bUTC=kTrue,&iOffset,&cErrorText])

Parses a date and time value conforming to RFC3339 and returns an Omnis date-time value and optionally the time zone offset in minutes.
Returns #NULL if the string cannot be parsed.

The parameters are:

$splitmultipart

The $splitmultipart allows you to split multipart content of a rest call, plus the MIME list returned by the OW3 methods that contain body part headers.

OW3.$splitmultipart(cContentType, xContent, &lMIMEList [,iDefCharSet=kUniTypeUTF8, &cErrorText])

Splits MIME-encoded multi-part xContent into lMIMEList.cContentType must include a boundary parameter. Returns true if successful. The parameters are:

The MIME list (for this call and for the other OW3 calls that generate a MIME list) now contains an additional column named bodypartheaders. This is a row containing a column for each non-empty header present for the body part. In addition, it has a column named "name" which contains the content-disposition header name parameter. All header names are normalized in the same way as those passed to RESTful services, that is, lower-case with any - characters removed.

Callback methods

$completed

When a worker is started using either $run or $start, it reports its completion by calling $completed. Override the $completed method of the worker object to receive this notification. It is called with a single row variable parameter. The columns of the row are specific to each type of worker object, so they are described in each specific worker object section.

$cancelled

To receive a notification that a request has been cancelled using $cancel, override the $cancelled method of the worker object. It is called with no parameters.

$progress

To receive progress notifications, override the $progress method of the worker object. OW3 worker objects generate notifications to $progress as and when some data has been transferred. Progress notifications will not be generated any more than once a second. Each notification receives a row variable parameter. The row has 4 columns.

For the OW3 FTP worker, $progress can be called for synchronous operations.

OAUTH2 Worker Object

OAUTH2 authorization is supported in the HTTP, IMAP, POP3, and SMTP workers via the OAUTH2 Worker Object in the OW3 Worker object package.

Refer to the HTTP, IMAP, POP3, and SMTP Worker Object examples in the Samples section of the Hub in the Studio Browser to see how to use OAUTH2 for authorization.

Why use OAUTH2

OAUTH 2.0 provides much improved security over and above simple username and password schemes. It is commonly used by many different service providers, such as Google mail, for which its use will become mandatory in 2020 (meaning less secure apps will no longer be supported). You can read about OAUTH 2.0 in RFC 6749 (https://tools.ietf.org/html/rfc6749)

An application wishing to use a service (using HTTP, IMAP, POP3, or SMTP) requires an Access Token of type “bearer”. The application needs to be registered with the service, so it can identify itself to the service, and the registration process provides the application with a Client Id and a Client Secret, that identify the application to the service.

As an initial step, the user of the service must authorize the application to use the service. To do this:

• The application opens a Web browser at the Authorization Endpoint (a URL) of the service.

• The authenticated user agrees that the application can access the service.

• The server hosting the Authorization URL redirects the browser to a URL supplied when opening the Web browser. This request contains an Authorization Code.

• The application makes a request to the Token Endpoint (a URL) sending it the Authorization Code.

• The server hosting the Token URL returns various pieces of information to the application, including: Access Token, Expiry of Access Token (recommended but not mandatory), Refresh Token (optional).

At this point, the application can use the Access Token to make requests to the service. Access Tokens are short-lived, typically being valid for about an hour. If the Token URL server also returned a Refresh Token, the application can use that after the Access Token has expired to obtain a new Access Token, without any further interaction with the user. Refresh Tokens typically have a long lifetime, but may be invalidated for various reasons, depending on the service implementation.

Single Sign-On (SSO)

Omnis does not provide Single Sign-On (SSO), but you can call into SSO services provided by Google or Microsoft, for example, for which Omnis would need to use OAUTH2 to access these services.

In this case, once you obtain the necessary access tokens, as long as you've selected the right scopes for what you intend to do, you can call those SSO services without having to prompt the user to login again and also refresh the tokens if they expire (as long as you are not past the refresh token's expiration time/date).

Obtaining Authorization

The OAUTH2 Worker allows you to obtain an Authorization Code, exchange it for tokens, and refresh tokens, using the $authorize() method on a background thread. The worker also contains methods to save and load the tokens and other related information to and from an encrypted binary block of data, which helps to protect key pieces of information such as the Refresh Token and Client Secret.

Note that you must always use an Object Reference to create the OAUTH2Worker object – this eliminates potential issues with the way Omnis uses the OAUTH2Worker as a property value.

The object reference to an OAUTH2Worker object containing the authorization information can be passed to the $oauth2 property in the HTTP, IMAP, POP3, and SMTP Workers to provide authorization.

The $addclientdetailstotokenrequest boolean allows you to include or remove client credentials from the body of a token request (when Omnis exchanges the authorization code for the access token).

OAUTH2 Properties

These properties are specific to the OAUTH2 Worker Object.

HTTP and General Properties

In addition to the OAUTH2 properties, the OAUTH2Worker also has various HTTP and general OW3 properties, that for example affect how the HTTP requests it makes are executed: the OAUTH2Worker makes two different HTTP requests: a request to exchange an Authorization Code for an Access Token, and a request to obtain a new Access Token using the Refresh Token.

OAUTH2 Standard Methods

$authorize

$authorize([iAuthFlow=kOW3OAUTH2authFlowCodeWithPKCE])

Starts the OAUTH2 authorization flow iAuthFlow on a background thread. Returns true if the thread was successfully started. Properties of the object cannot be assigned while $authorize() is running.

$authorize() opens a Web Browser at the authorization URL, passing the URL various parameters in the query string, such as the Client Id using the value of the $clientid property.

How the Web Browser is opened depends on the context in which $authorize() is called.

When executed within the context of a thick client (non-remote) task, $authorize() uses the $webbrowser property to control which browser it opens (note that you cannot use $authorize() with a thick client task when running in the headless server). It should be noted that when running in the thick client, $authorize() always uses a web browser rather than an embedded obrowser control due to best practice considerations documented in RFC 8252: https://www.rfc-editor.org/rfc/rfc8252.txt

To use $authorize() in the Runtime version of Omnis, you must set the disableInRuntime item in the ‘server’ section of the config.json file to false.

When executed within the context of a remote task, $authorize() will only work if the remote task is a JavaScript Client remote task. In this case, it uses the $showurl() mechanism of the JavaScript Client to open a browser window or tab. Note that in this case, you cannot execute both $authorize() and $showurl() in response to the same JavaScript client event.

When using the authorization flows that redirect the browser to a URI, $authorize() determines the redirect URI as follows.

For the thick client, it uses a loopback URI, to 127.0.0.1. Note that if the version of Omnis is not a server version, Omnis will still open a server port with limited support for OAUTH2 only, to allow the Authorization Code to be received via the redirect URI.

For the JavaScript client, $authorize() uses the RESTful URI determined from the Omnis server configuration. Note that this means that if you are using a Web Server to handle requests for your Omnis server, you need to set up the Omnis Web Server plugin for both the JavaScript client and RESTful requests.

$authorize() takes a single parameter, iAuthFlow, which can have one of the following constant values (kOW3OAUTH2authFlowCodeWithPKCE is the default):

Note that you would normally use PKCE unless the service does not support it.

Manual code support, via the clipboard, is provided in case you do not want to open up a port for the redirect URI when running in the thick client; however, note that not all services support the redirect URI urn:ietf:wg:oauth:2.0:oob.

When $authorize() completes (which if successful means that is has opened the browser, received the Authorization Code, and exchanged it for an Access Token etc) it generates a call to the callback method $completed().

$setauthcode

$setauthcode(cAuthCode)

Returns Boolean true for success.

Only applicable to kOW3OAUTH2authFlowManualCode and kOW3OAUTH2authFlowManualCodeWithPKCE, when the $authorize() thread is waiting for the Authorization Code. Called from the application to supply the pasted Authorization Code using the cAuthCode parameter.

$save

$save(&xOAUTH2[,xKey])

Saves the properties ($clientid, $clientsecret, $authorizeurl, $tokenurl, $scope, $accesstoken, $refreshtoken and $accesstokenexpiry) to the encrypted binary buffer xOAUTH2.

xKey is a 256 bit AES encryption key. If you omit xKey, OW3 uses a hard-coded default key.

Returns Boolean true for success.

$save provides a convenient way to save all of the OAUTH2 parameters required for communicating with a service. In particular, it lets you safely store the Refresh Token, so you can minimise the number of occasions on which a user needs to authorize access using $authorize().

You can further protect your client secret, by including the encrypted buffer generated by $save in your release tree.

$load

$load(xOAUTH2[,xKey])

Loads the properties ($clientid, $clientsecret, $authorizeurl, $tokenurl, $scope, $accesstoken, $refreshtoken and $accesstokenexpiry) from the encrypted binary buffer xOAUTH2 previously generated using $save().

xKey is a 256 bit AES encryption key. If you omit xKey, OW3 uses a hard-coded default key. You must use the same key as that used when calling $save().

Returns Boolean true for success.

Grant Types

From Studio 11, the OAUTH2 Worker supports multiple grant types: authorization_code, password, and client_credentials (as per RFC 6749 sections 4.1, 4.3 and 4.4).

The $granttype property takes one of the following grant types:

• kOW3OAUTH2grantAuthorizationCode (the default)
  the Authorization Code grant type (behaves as previous versions)

• kOW3OAUTH2grantPassword
  the Password grant type requires the new $username and $password properties to be specified

• kOW3OAUTH2grantClientCredentials
  the Client Credentials grant type requires $clientid and $clientsecret

The $granttype property is set to kOW3OAUTH2grantAuthorizationCode by default which corresponds to behavior versions prior to Studio 11, so existing code should run as before.

When $granttype is set to kOW3OAUTH2grantPassword, the $password and $username properties can be used to retrieve an authorization token. However, this is deemed to be insecure, when compared to more secure methods, and should not be used (unless a legacy system requires it).

When $granttype is set to kOW3OAUTH2grantClientCredentials, the properties $clientid and $clientsecret are used to obtain the authorization token. Note that when using this grant type, the OAUTH2 server may not return a refresh token (as per RFC 6749 section 4.4.3).

OAUTH2 Callback Methods

$tokensrefreshed

The OAUTH2Worker has one non-standard callback method, $tokensrefreshed. The OAUTH2Worker generates a call to this method after it has successfully refreshed the tokens while it is being used in conjunction with the HTTP/IMAP/POP3/SMTP worker.

$tokensrefreshed() is called with no parameters; at this point, the worker has been updated with the new Access Token, Access Token Expiry and Refresh Token. A typical implementation of $tokensrefreshed() would use $save() to save the current tokens etc and then write the encrypted buffer to disk. It should be noted that calling the server to refresh tokens can result in a different updated Refresh Token - this needs to be used to refresh tokens the next time a refresh is required.

HTTP and General Methods

The OAUTH2Worker supports the normal methods $cancel(), $getsecureoptions() and $setsecureoptions(). The latter two relate to how secure connections to the Token URL are established.

HTTP Callback Methods

The OAUTH2Worker generates calls to the standard callback methods $cancelled() and $completed(). These correspond to a call to $authorize() to start the authorization code flow. The completion row passed as a parameter to $completed() has columns as follows:

HTTP, IMAP, POP3, and SMTP Workers

Once you have used $authorize() to obtain an Access Token, you need to make the Access Token available to the worker with which OAUTH2 authorization is required. You do this by assigning a new $oauth2 property of the HTTP, IMAP, POP3, or SMTP worker:

• $oauth2
  Property that is an object reference to an OAUTH2Worker object containing the authorization information required to make requests to the server. Clear this property by assigning #NULL to it. $authorize() cannot run while the OAUTH2Worker is assigned to $oauth2

The supported workers use $oauth2 to obtain the Access Token for the request. To do this, it uses the following logic:

• If there is no Refresh Token ($refreshtoken is empty), it uses $accesstoken.

• If the $accesstokenexpiry is #NULL (there is no expiry date and time), it uses $accesstoken.

• If the expiry date time is more than 5 seconds away, it uses $accesstoken

• Finally, it uses $refreshtoken to refresh the token(s). If successful, it generates a call to $tokensrefreshed() in the OAUTH2Worker and it uses the new $accesstoken

You should note that there is a chance the request will fail when it is made near to the 5 second window before the Access Token expires. You should be prepared to handle this type of error in $completed, possibly retrying the request.

HTTP

After assigning $oauth2, the parameters iAuthType, cUserName, and cPassword passed to $init() are ignored in favour of using the Access Token stored in $oauth2.

IMAP, POP3, SMTP

After assigning $oauth2, the cPassword parameter passed to $init() is ignored in favour of using the Access Token stored in $oauth2. Note that cUserName is still required.

OAUTH2 Example

The following code extracts are taken from the SMTP Worker Object in the Samples section of the Hub in the Studio Browser, which uses the OAUTH2 object for authorization.

# create the OAUTH2 object
Do $extobjects.OW3.$objects.OAUTH2Worker.$newref() Returns iOAUTH2

# setup the SMTP object 
Do $objects.oSMTPWorker.$newref() Returns iSmtp
Do iSmtp.$setCallingInst($cinst)

# set iOAUTH2 properties from settings contained in a form 
Calculate iOAUTH2.$callbackinst as $cinst
  
Calculate iOAUTH2.$clientid as iOAUTH2ClientID
Calculate iOAUTH2.$clientsecret as iOAUTH2ClientSecret
Calculate iOAUTH2.$authorizeurl as iOAUTH2CodeURL
Calculate iOAUTH2.$tokenurl as iOAUTH2TokenURL
Calculate iOAUTH2.$scope as iOAUTH2Scope
  
Calculate iOAUTH2.$followredirects as iOAUTH2FollowRedirects
Calculate iOAUTH2.$timeout as iOAUTH2Timeout
Calculate iOAUTH2.$proxyserver as iOAUTH2ProxyServer
Calculate iOAUTH2.$proxytunnel as iOAUTH2ProxyTunnel
Calculate iOAUTH2.$proxyauthtype as iOAuth2ProxyAuthList.iAuthType
Calculate iOAUTH2.$proxyauthusername as iOAUTH2ProxyUser
Calculate iOAUTH2.$proxyauthpassword as iOAUTH2ProxyPassword
  
Calculate iOAUTH2.$protocollog as iOAUTH2LogTypeList.C2
  
Calculate iAuthorizing as kTrue
Do iOAUTH2.$authorize(iOAUTH2AuthorizationFlowList.iOAUTH2FlowType) Returns lOK
If not(lOK)
  OK message {[iOAUTH2.$errortext]}
End If 
Calculate iAuthorizing as kFalse

# $start method 
If iAuthorizing
  OK message {Cannot execute while authorizing}
  Quit method 
End If 

If iUseOAUTH2   ## option on form to use OAUTH2
  Do iSmtp.$oauth2.$assign(iOAUTH2)
Else
  Do iSmtp.$oauth2.$assign(#NULL)
End If 

HTTP Worker Object

The HTTPClientWorker provides client HTTP support. For example, you can POST data to a server, execute a RESTful request, or download a file from a server.

The HTTP Worker supports the following externals:

• curl version 7.84.0

• libssh2 version 1.9.0

• mbedTLS version 2.16.2

There is an HTTP OW3 Worker Object example in the Samples section of the Hub in the Studio Browser.

Properties

The HTTPClientWorker has the following properties in addition to the base worker properties described earlier:

Constants

The HTTPClientWorker uses the following constants for the iMethod parameter in the $init method (in addition to the base worker constants described earlier):

The following constants are for the iAuthType parameter in the $init method:

The following constants are for the vContent parameter in the $init method:

Methods

HTTPClientWorker has the methods described in this section in addition to the base worker methods described earlier.

Normal methods

$init

$init(cURI [,iMethod=kOW3httpMethodGet, lHeaders=#NULL, vContent='', iAuthType=kOW3httpAuthTypeNone, cUserName='',cPassword=''])

Called to prepare the object to execute a request, before calling $run or $start; the URI is the only required parameter.

Returns Boolean true for success, or returns false and sets $errorcode and $errortext if an error occurs.

The parameters are:

NOTE: If you call $init when a request is already running on a background thread, the object will cancel the running request, and wait for the request to abort before continuing with $init.

Calculate accessKey as 'AKIA...'
Calculate region as 'us-east-1'
Calculate service as 's3'
Do iHttp.$init(iURI,iMethodList.iMethod,iHeaderList,,kOW3httpAuthTypeAWSv4,con(accessKey,'/',region,'/',service),'jYN/BU...') Returns lOk

Do iHttp.$curloptions.$assign(list(row(84,3)))

Example

The following code could be used to prepare an HTTPClientworker object using $init, and then $run can be used to execute the HTTP method. The method returns the content of the web page stored in iURI, e.g. ww.omnis.net.

# $execute method
Do method checkHttpObject ## sets up the HTTP object ref var
Do method setupLogging ## sets up logging based on user choice
If len(iTempContent)
    Do iHttp.$init(iURI,iMethodList.iMethod,iHeaderList,iTempContent,iAuthList.iAuthType,iUser,iPassword) Returns lOk
Else
    If iSendContentMode=1
        Do iHttp.$init(iURI,iMethodList.iMethod,iHeaderList,row(iContentPath),iAuthList.iAuthType,iUser,iPassword) Returns lOk
    Else If iSendContentMode=2
        Do iHttp.$buildmultipart(iContentPath)
        Do iHttp.$init(iURI,iMethodList.iMethod,iHeaderList,kOW3httpMultiPartFormData,iAuthList.iAuthType,iUser,iPassword) Returns lOk
    Else If iSendContentMode=0
        Do iHttp.$init(iURI,iMethodList.iMethod,iHeaderList,iContent,iAuthList.iAuthType,iUser,iPassword) Returns lOk
    End If 
End If 
If not(lOk)
    OK message {Error [iHttp.$errorcode]: [iHttp.$errortext]}
    Quit method kFalse
End If 
If pRun
    Do iHttp.$run() Returns lOk
Else
    Do iHttp.$start() Returns lOk
    If lOk
        Calculate $cinst.$objs.ScrollBox.$objs.cancel.$enabled as kTrue
        Calculate $cinst.$objs.ScrollBox.$objs.execute.$enabled as kFalse
        Calculate $cinst.$objs.ScrollBox.$objs.executethencancel.$enabled as kFalse
    End If 
End If 
If not(lOk)
    OK message {Error [iHttp.$errorcode]: [iHttp.$errortext]}
    Quit method kFalse
End If 
Quit method kTrue

$multipartclear

$multipartclear()

Frees any previously generated multipart/form-data content. Note that calling $run or $start with kOW3httpMultiPartFormData results in the multipart/form-data content being automatically freed after use.

Returns Boolean true for success, or returns false and sets $errorcode and $errortext if an error occurs.

$multipartaddfield

$multipartaddfield(cName, cFieldData [,lPartHeaders])

Adds a field part to the multipart/form-data content stored in the worker object. To send this content specify kOW3httpMultiPartFormData as the vContent parameter to $init().

Returns Boolean true for success, or returns false and sets $errorcode and $errortext if an error occurs.

The parameters are:

$multipartaddfile

$multipartaddfile(cName, vFileData [,cFileName='', lPartHeaders])

Adds a file part to the multipart/form-data content stored in the worker object. A file part indicates to the server that a file is being uploaded. To send this content specify kOW3httpMultiPartFormData as the vContent parameter to $init().

Returns Boolean true for success, or returns false and sets $errorcode and $errortext if an error occurs.

The parameters are:

Callback methods

$completed

The standard $completed callback is passed a row variable parameter with the following columns:

WebSocket Client Support

$init

To initialise the OW3 HTTP worker object so that it is ready to create a WebSocket client connection, call $init with parameters as follows:

The standard OW3 properties $state, $errortext, $errorcode, $threadcount, $protocollog, $timeout, $callprogress and $curloptions all apply when connecting to a WebSocket server.

The standard OW3 methods $getsecureoptions and $setsecureoptions apply when connecting to a WebSocket server.

$run and $start

You cannot use $run to establish a WebSocket connection, since multiple threads are required to make it usable. So if you try to use $run, the worker returns kFalse and sets $errorcode and $errortext.

To establish a WebSocket connection, call $start. If $start succeeds, then the worker attempts to establish the connection to the WebSocket server in another thread.

If the connection cannot be established, the worker generates a notification to $completed, with a non-zero value in the errorCode member of the notification row parameter.

If the connection is established successfully (and is therefore open and ready for data transfer), the worker generates a notification to the new method $ws_onconnect. Override this method to receive this notification. $ws_onconnect receives a single row variable as its parameter. This row variable has a single column, responseHeaders, which is a row with a single column for each response header received from the server in the final HTTP protocol exchange resulting in the 101 (web socket protocol handshake) HTTP status code.

As soon as you have received the $ws_onconnect notification, the WebSocket is ready to send and receive data.

$wssend

After you have received the $ws_onconnect notification, you can send data using the method $wssend:

$wssend(vMessage)

Sends the supplied message on a connected web socket. Returns true if successful, which means the message has been queued for sending.

If vMessage is a character value, the worker converts it to UTF-8 before sending it as a text message; otherwise the value is treated as binary and sent as a binary message.

Receiving Data

Each message received from the WebSocket server generates a $ws_onmessage notification. Override this method to receive these notifications. $ws_onmessage receives a single row variable parameter, with 2 columns (named data and utf8). Column data is the binary data and column utf8 is boolean true if the data is UTF-8.

$wsclose

The client can close the WebSocket connection by calling the method $wsclose:

$wsclose([bDiscardUnsentMessages=kFalse,iStatusCode=1000,cReason=''])

Closes the connection to the web socket server. $completed() will be notified when the connection has closed. The row passed to $completed has closeStatus and closeReason columns that receive the values sent in the close frame to the server.

Pass bDiscardUnsentMessages as kTrue, to discard any completely unsent queued messages before sending the close frame to the server.

iStatusCode is an integer status code that indicates the reason for closure (one of the values in section 7.4 of RFC6455).

cReason is some optional text that indicates the reason for closure.

Server close

The server can send a close frame to the client, telling the client it is closing the connection. The client responds with a close frame, before the connection closes. Again, $completed is notified to tell the object that the connection has closed.

The row passed to $completed has closeStatus and closeReason columns that receive the values sent in the close frame from the server.

$cancel

You can use $cancel to terminate the connection in a non-graceful manner.

Ping-pong

If the client receives a Ping from the server, it automatically responds with a Pong. You can also set up the client to automatically Ping the server, and generate an error (closing the connection) if a Pong is not received. To do this, use these two properties:

$wspinginterval: If non-zero, and the connection is to a web socket server, the HTTP worker sends a Ping frame to the server every $wspinginterval seconds of inactivity, and closes the connection if a Pong frame is not received after $wspongtimeout seconds. Defaults to zero.

$wspongtimeout: The number of seconds (1-60, default 5) the client waits to receive a Pong frame after sending a Ping frame as a result of the $wspinginterval timeout expiring.

Timeout

The object restarts the $timeout timer each time it sends or receives some data.

SMTP Worker Object

The SMTPClientWorker provides client SMTP support, allowing you to use the worker to send emails, including bulk emails via a mailshot. The following sections describe the SMTP worker properties, constants and methods.

There is an SMTP OW3 Worker Object example in the Samples section of the Hub in the Studio Browser.

Properties

The SMTPClientWorker has the following properties in addition to the base worker properties described earlier:

Constants

The SMTPClientWorker uses the following constants in addition to the base worker constants described earlier:

Methods

SMTPClientWorker has the methods described in this section in addition to the base worker methods described earlier.

Normal methods

$init

$init(cURI, cUser, cPassword, vFrom, lTo, lCc, lBcc, cSubject, cPriority, lHeaders, vContent [,bMailshot=kFalse])

Called to prepare the object to execute a request, before calling $run or $start.

Returns Boolean true for success, or returns false and sets $errorcode and $errortext if an error occurs.

The parameters are:

NOTE: If you call $init when a request is already running on a background thread, the object will cancel the running request, and wait for the request to abort before continuing with $init.

Example

The $init method can be used to prepare the SMTPClientWorker object to be executed using the $run or $start method. In this case, iSmtp is an object reference variable with its subtype set to an object class, which has its $superclass set to the SMTPClientWorker in the OW3 worker objects group.

# $start method
Do method setupLogging ## set up logging
Calculate iSmtp.$timeout as iTimeout ## set properties via window fields
Calculate iSmtp.$callprogress as iCallProgress
Calculate iSmtp.$keepconnectionopen as iKeepConnectionOpen
Calculate iSmtp.$requiresecureconnection as iRequireSecureConnection
Calculate iSmtp.$callmailshotprogress as iCallMailshotProgress
Do method $splitaddressentry (iFrom,lFromAddress,lFromDescription) Returns lOk
If not(lOk)
    OK message {From "[iFrom]" is invalid}
    Quit method kFalse
End If 
Calculate lOk as $cinst.$makerecipientlist(lToList,iTo)
If not(lOk)
    OK message {From "[iTo]" is invalid}
    Quit method kFalse
End If 
Calculate lOk as $cinst.$makerecipientlist(lCcList,iCc)
If not(lOk)
    OK message {From "[iCc]" is invalid}
    Quit method kFalse
End If 
Calculate lOk as $cinst.$makerecipientlist(lBccList,iBcc)
If not(lOk)
    OK message {From "[iBcc]" is invalid}
    Quit method kFalse
End If 
If iCallMailshotProgress
    Set reference lMailshotProgressItem to $clib.$windows.wMailshotProgress.$openmodal("*",kWindowCenterRelative,$cinst,lToList.$linecount,$cinst)
End If 
Do iSmtp.$setMailshotProgressInst(lMailshotProgressItem)
If iNoMIME
    If len(lFromDescription)
        Do iSmtp.$init(iServerURI,iUser,iPassword,row(lFromAddress,lFromDescription),lToList,lCcList,lBccList,iSubject,iPriorityList.iPriorityValue,iExtraHeaderList,lBinContent,iMailshot) Returns lOk
    Else
        Do iSmtp.$init(iServerURI,iUser,iPassword,lFromAddress,lToList,lCcList,lBccList,iSubject,iPriorityList.iPriorityValue,iExtraHeaderList,lBinContent,iMailshot) Returns lOk
    End If 
Else
    If len(lFromDescription)
        Do iSmtp.$init(iServerURI,iUser,iPassword,row(lFromAddress,lFromDescription),lToList,lCcList,lBccList,iSubject,iPriorityList.iPriorityValue,iExtraHeaderList,lMIMElist,iMailshot) Returns lOk
    Else
        Do iSmtp.$init(iServerURI,iUser,iPassword,lFromAddress,lToList,lCcList,lBccList,iSubject,iPriorityList.iPriorityValue,iExtraHeaderList,lMIMElist,iMailshot) Returns lOk
    End If 
End If 
If not(lOk)
    OK message {$init error [iSmtp.$errorcode]: [iSmtp.$errortext]}
    Quit method kFalse
End If 
If pRun
    Do iSmtp.$run() Returns lOk
Else
    Do iSmtp.$start() Returns lOk
End If 
If not(lOk)
    OK message {$run error [iSmtp.$errorcode]: [iSmtp.$errortext]}
    Quit method kFalse
Else If not(pRun)
    Calculate $cinst.$objs.scrollbox.$objs.cancel.$enabled as kTrue
    Calculate $cinst.$objs.scrollbox.$objs.start.$enabled as kFalse
    Calculate $cinst.$objs.scrollbox.$objs.startthencancel.$enabled as kFalse
End If 
Quit method kTrue

Callback methods

$completed

The standard $completed callback is passed a row variable parameter with the following columns:

$mailshotprogress

If the request is a mailshot, and $callmailshotprogress is kTrue, the worker generates a notification to $mailshotprogress each time it sends (or fails to send) the message to a recipient. $mailshotprogress is passed a row variable parameter with the following columns:

FTP Worker Object

The FTPClientWorker provides client FTP support, allowing you to transfer files. The following sections describe the FTP worker properties, constants and methods.

There is an FTP OW3 Worker Object example in the Samples section of the Hub in the Studio Browser.

Properties

The FTPClientWorker has the following properties in addition to the base worker properties described earlier:

Constants

The FTPClientWorker uses the following constants in addition to the base worker constants described earlier. These constants are all actions specified in the iAction parameter used with the $init method to indicate the action to perform, so this section should be read in conjunction with the section describing the $init method:

Directory list for kOW3ftpActionListDirectory

FTP does not have a standard syntax for the data returned by the LIST command, so the FTP worker attempts to parse the results of the ListDirectory action, based on some typical syntaxes supported by many servers. The detailed list has 8 columns, as follows:

• The full text returned by the server. This maintains compatibility with previous versions of the OW3 FTP worker, and may contain additional information not extracted by the parser.

• The file name.

• Boolean. True if the entry is probably a directory.

• Boolean. True if the entry is probably a file.

• File size in bytes.

• Modification date of the file.

• Boolean. True if the modification date is in the local time zone of the client. False means the time zone of the modification date is unknown.

• If not empty, the server id of the file or directory. A character string.

Uploading or downloading multiple files

When using kOW3ftpActionGetFileMulti or kOW3ftpActionPutFileMulti, to upload or download multiple files, the row passed to $progress has an extra column (requestNumber) which corresponds to the line number in the vParam list currently being transferred.

The $completed method is called with a successful status if all transfers are completed successfully. If at least one failed, the error code is 10312 (at least one transfer during a kOW3ftpActionGetFileMulti or kOW3ftpActionPutFileMulti action failed). In addition, the resultList column contains a list with a line for each transfer, containing error code, error info and FTP status code.

Methods

FTPClientWorker has the methods described in this section in addition to the base worker methods described earlier. $progress can be called for synchronous (as well as asynchronous) operations for the FTP worker.

Normal methods

$init

$init(cURI, cUser, cPassword, iAction, cServerPath, vParam)

Called to prepare the object to execute a request, before calling $run or $start.

Returns Boolean true for success, or returns false and sets $errorcode and $errortext if an error occurs.

The parameters are:

NOTE: If you call $init when a request is already running on a background thread, the object will cancel the running request, and wait for the request to abort before continuing with $init.

Example

You could create an FTP client window with various fields for FTP host name, username, password, timeout setting, server character set, and a list of FTP commands or actions as they are defined in the $init() method. A button could initiate the FTP command, executing the appropriate action depending on the one chosen by the end user, using the following code:

# start() method
# iFtp is an Object reference variable with the FTPClientWorker as Subtype 
# iActionList (List) variable assigned to list of actions on the window 
Do method setupLogging
Calculate iFtp.$timeout as iTimeout ## fields on the FTP window
Calculate iFtp.$callprogress as iCallProgress
Calculate iFtp.$keepconnectionopen as iKeepConnectionOpen
Calculate iFtp.$requiresecureconnection as iRequireSecureConnection
Calculate iFtp.$servercharset as iServerCharsetList.C2
Calculate iFtp.$responsepath as iResponsePath
If iActionList.C2=kOW3ftpActionPutFile.C2=kOW3ftpActionAppendFile
    If iSendContentMode=0
        ReadBinFile (iContentPath,iContent)
        Do iFtp.$init(iServerURI,iUser,iPassword,iActionList.C2,iServerPath,iContent) Returns lOk
    Else
        Do iFtp.$init(iServerURI,iUser,iPassword,iActionList.C2,iServerPath,row(iContentPath)) Returns lOk
    End If 
Else If iActionList.C2=kOW3ftpActionSetPermissions
    Do iFtp.$init(iServerURI,iUser,iPassword,iActionList.C2,iServerPath,iPermissions) Returns lOk
Else If iActionList.C2=kOW3ftpActionExecute
    Do iFtp.$init(iServerURI,iUser,iPassword,iActionList.C2,iServerPath,iCommandList) Returns lOk
Else If iActionList.C2=kOW3ftpActionListDirectory
    Do iFtp.$init(iServerURI,iUser,iPassword,iActionList.C2,iServerPath,iNamesOnly) Returns lOk
Else If iActionList.C2=kOW3ftpActionDelete
    Do iFtp.$init(iServerURI,iUser,iPassword,iActionList.C2,iServerPath,iPathIsDirectory) Returns lOk
Else
    Do iFtp.$init(iServerURI,iUser,iPassword,iActionList.C2,iServerPath) Returns lOk
End If 
# then $run or $start is called 
If not(lOk)
    OK message {$init error [iFtp.$errorcode]: [iFtp.$errortext]}
    Quit method kFalse
End If 
If pRun
    Do iFtp.$run() Returns lOk
Else
    Do iFtp.$start() Returns lOk
End If 
If not(lOk)
    OK message {$run error [iFtp.$errorcode]: [iFtp.$errortext]}
    Quit method kFalse
Else If not(pRun)
    Calculate $cinst.$objs.scrollbox.$objs.cancel.$enabled as kTrue
    Calculate $cinst.$objs.scrollbox.$objs.start.$enabled as kFalse
    Calculate $cinst.$objs.scrollbox.$objs.startthencancel.$enabled as kFalse
End If 
Quit method kTrue

Callback methods

$completed

The standard $completed callback is passed a row variable parameter with the following columns:

Example

Following on from the $init example above, you could create code in the $completed method to handle the response from the FTP server returned in the pResults parameter: the code writes the log to an HTML file and displays it in the oBrowser object.

# $completed method
Calculate iResponse as pResults
Calculate iErrorCode as pResults.errorCode
Calculate iErrorText as pResults.errorInfo
If iUsingLogBrowser
    Do FileOps.$deletefile(iLogHTMLPath)
    WriteBinFile (iLogHTMLPath,iResponse.log)
    Calculate iLogBrowser.$urlorcontrolname as con("file://",replaceall(iLogHTMLPath," ","%20"))
Else
    Calculate iLog as iResponse.log
End If 
Do $cinst.$redraw()
Calculate $cinst.$objs.tabpane.$currenttab as 3

Secure FTP (SFTP)

The FTP Worker Object supports Secure FTP (SFTP). There are some differences in functionality when using SFTP:

• You use URLs of the form SFTP:// to request an SFTP connection.

• You must explicitly select a server character set - kUniTypeAuto will cause the worker to return an error.

• The append file action is not supported.

• If you have written code that uses the execute action, be aware that SFTP servers support different commands to FTP servers.

• The remaining actions work as expected.

In addition, there are some properties and methods, primarily related to how a connection is authenticated. SFTP does not use TLS, so the secure options related to that only affect FTPS and FTP connections to be upgraded to TLS.

The FTP worker object has the properties:

• $sshenablecompression
  If true, SSH compression is enabled for SFTP connections, resulting in a request to the server to enable compression; the server may ignore the request. Defaults to false

• $sshknownhostsfile
  The full pathname of the SSH known hosts file used for SFTP. Defaults to the path of clientserver/client/ow3_sftp_known_hosts in the Studio tree. Set this to empty to allow connections (insecurely) to any host

• $sshknownhostsaction
  A sum of kOW3sshKHAction... constants (default kOW3sshKHActionReject) specifying what occurs if $sshknownhostsfile is present, and a connection is to be made to a server not in the file, or a server in the file with a host key mismatch

• $sshauthtypes
  A sum of kOW3sshAuthType... constants specifying the allowed authentication types when establishing a connection to the server; the default is kOW3sshAuthTypePublicKey + kOW3sshAuthTypePassword + kOW3sshAuthTypeHost + kOW3sshAuthTypeAgent

The FTP worker object has the methods:

• $getsshoptions()
  $getsshoptions([&cServerPublicKeyMD5,&cClientPublicKeyFile,&cPrivKeyFile,&cPrivKeyPassword)]) gets the options that affect how SSH connections are established for SFTP

• $setsshoptions()
  $setsshoptions([cServerPublicKeyMD5='',cClientPublicKeyFile='',cPrivKeyFile='',cPrivKeyPassword='']) sets the options that affect how SSH connections are established for SFTP. The parameters are:
  cServerPublicKeyMD5:The 128 bit MD5 checksum of the server's public key (supplied as a 32 character ASCII hex string).If not empty,the SFTP client will reject the connection to the server unless the MD5 checksums match
  cClientPublicKeyFile:The pathname of the client's public key. If empty,the client will try to compute the public key from the private key
  cPrivKeyFile:The pathname of the client's private key file
  cPrivKeyPassword:The private key file password

Some or all of the SSH options may be optional, depending on the authentication type chosen.

Keys

When using SFTP, the public and private keys need to be in OpenSSH format. If you have a differently formatted key, such as SSH2 from RFC4716, perhaps generated with PuTTY, you can convert the key using a terminal.

For example, converting a public key with ssh-keygen:

ssh-keygen -i -f [path to .pub key]

will print out the OpenSSH-format public key which can be copied into its own new .pub file.

Converting a private .ppk key:

puttygen [path to .ppk key] -O private-openssh -o [path to new .pem file]

will convert the .ppk key generated from PuTTY to a private OpenSSH-format private key.

IMAP Worker Object

The IMAPClientWorker provides client IMAP support, allowing you to use the worker to manage emails stored on an IMAP server. The following sections describe the IMAP worker properties, constants and methods.

There is an IMAP OW3 Worker Object example in the Samples section of the Hub in the Studio Browser.

Properties

The IMAPClientWorker has the following properties in addition to the base worker properties described earlier:

Constants

The IMAPClientWorker uses the following constants in addition to the base worker constants described earlier. These constants are all actions used with the $init method to indicate the action to perform, so this section should be read in conjunction with the section describing the $init method:

Methods

IMAPClientWorker has the methods described in this section in addition to the base worker methods described earlier.

Normal methods

$init

$init(cURI, cUser, cPassword, iAction, cMailboxName, vParam1, vParam2)

Called to prepare the object to execute a request, before calling $run or $start.
Returns Boolean true for success, or returns false and sets $errorcode and $errortext if an error occurs.

The parameters are:

NOTE: If you call $init when a request is already running on a background thread, the object will cancel the running request, and wait for the request to abort before continuing with $init.

$chartoutf7

$chartoutf7(cChar)

Returns a binary value (containing 7 bit characters) that is the IMAP UTF-7 representation of cChar (note that IMAP uses a special variant of UTF-7, and this method generates that variant).

The parameters are:

$utf7tochar

$utf7tochar(xUtf7[,bAllowCRLF=kTrue])

Converts IMAP UTF-7 xUtf7 to character and returns the result. Optionally allows CRLF sequences in the data and replaces them with CR in the result (note that IMAP uses a special variant of UTF-7, and this method expects that variant in xUtf7).

The parameters are:

Callback methods

$completed

The standard $completed callback is passed a row variable parameter with the following columns:

kOW3imapActionListMailboxes:

kOW3imapActionListMessages:

kOW3imapActionFetchMessage:

kOW3imapActionSetMessageFlags:

kOW3imapActionAppendMessage:

kOW3imapActionExecute:

JavaScript Worker Object

The JavaScript Worker Object allows you to execute JavaScript methods inside node.js by making the request in Omnis code by calling a Worker Object method, and receiving the results via a worker callback. The node.js framework is embedded into Omnis Studio, and contains many open source third-party modules that can be used from inside your Omnis code. All traffic sent between the Omnis and node.js processes is encrypted. For example, the library ‘xml2js’ is included in Omnis Studio, which converts XML to JSON: in addition, support for ZIP can be added using the node.js jszip module, which is described at the end of this section.

There is a JS Worker example in the Samples section of the Hub in the Studio Browser.

Enabling JavaScript Methods

Method calls arrive as an HTTP request from Omnis, and respond with their results as HTTP content. The worker executes methods sequentially, but in a separate process.

Omnis has a simple structure where you can write a JavaScript module containing one or more methods, and then call methods via their module and method name.

In the Omnis data folder, there is a folder called ‘jsworker’, where modules required by ow3javascript.js are located. You can install additional node.js modules in this folder using the npm -i command when running in the folder - these might be modules for which you want to provide an interface from Omnis.

There are two key files in this folder, which must always be present:

• omnis_calls.js - a module which provides an interface for methods to return their results to Omnis.

There are also two example module files, omnis_test and omnis_zip. These provide Omnis modules named 'test' and 'omnis_zip'. Each module file must have an entry in omnis_modules.js (or be automatically loaded). Each module file provides a table of methods that can be called from Omnis.

Note that ‘jsworker’ in the data folder may not be considered suitable for deployment, since the data folder is writeable. The worker provides the ability for you to structure things differently when you deploy your application, but is fine for development.

Auto Loading modules

From Studio 11, the JS Worker will pick up any modules you have added automatically if they are placed in the jsworker folder. Any modules that you have added in their own folder, with a package.json or index.js, are picked up automatically by the JS Worker. (This is in addition to using the hard-coded moduleMap method, as described below.)

Creating Modules

The only requirement of a module is that it exports a default object containing a function named "call", which receives parameters: (method, param, response).

This function should handle the calling of your module's method(s), and sending a response to Omnis, using the methods available in the omnis_calls module.

export default omnis_calls.omnisModuleDefaultExport(methodMap);

See the omnis_test example module for the recommended way of implementing this.

Creating the worker

The sub-type of the external object is OW3 Worker Objects\JAVASCRIPTWorker. You can use either an Object variable or an Object Reference variable, either directly if you set $callbackinst to receive results, or by subclassing the external object with an Omnis object.

Properties

The JavaScript worker only has the standard worker properties: $state, $threadcount, $errorcode and $errortext.

Methods

Called Methods

$init()

$init([cPath, bDebugNodeJs=kFalse])

Initialize the object so it is ready to execute JavaScript method calls. Returns true if successful. You must call $init() before any other methods.

• cPath
  allows you to override the default NODE_PATH module search path set by the worker. The default path is <Omnis data folder>/jsworker. If you override this path, the various JavaScript modules that are mandatory for the worker to operate must still be able to be located.

• bDebugNodeJs
  is a Boolean that indicates if you want to be able to debug node.js, for example using Chrome. It is possible that you may not be able to start the worker if you set this for more than one active JavaScript worker, as node.js requires a debug port to be available. To debug the JavaScript in Chrome, navigate to chrome://inspect, and then open the dedicated debug tools for node.js via the link.

$start()

$start()

Runs the JavaScript worker in a background thread. Returns true if the worker was successfully started.

After you call $start(), the background thread starts up a node.js process which will process JavaScript method calls. You can make multiple method calls to the same process, so there is no need to call $start() frequently, which means the overhead of starting the node.js process is minimal.

$cancel()

$cancel()

Use this to terminate the node.js process. Any in-progress method calls may not complete.

$callmethod()

$callmethod(cModule, cMethod, vListOrRow [,bWait=kFalse, &cErrorText, vTag])

Call the method passing it a single parameter which is the JavaScript object representation of vListOrRow. Optionally wait for the method to complete. Returns true if successful.

• cModule and cMethod (Character)
  identify a module, and a method within the module, to call, as described above.

• vListOrRow (Variant)
  will be converted to JSON and passed to the method as its parameter. This means that you should be aware of data that will not map to JSON, and avoid trying to pass that to $callmethod.

• bWait (Boolean)
  indicates if the caller wishes to suspend execution until the method completes. If you use bWait, then a completion callback will occur before $callmethod returns.

• cErrorText (Character)
  receives text describing the error if $callmethod fails; code 460 for module not found, and 461 for method not found.

• vTag (Variant)
  (for Studio 11) if supplied, some data can be passed to $methoderror or $methodreturn in the column __tag of the row parameter. This can be used, for example, to identify the caller when the worker object is shared by several instances.

Callback Methods

$cancelled

Override this to receive a notification that the request to cancel the worker has succeeded.

$workererror

$workererror(wError)

Override this method to receive reports of errors from the worker that are not related to calling a method, e.g. failure to start node.js. The worker thread exits after generating this notification.

• wError
  has two columns, an Integer named errorCode and a Character string named errorInfo.

$methoderror

$methoderror(wError)

Override this method to receive reports of the failure of an attempt to call a method with $callmethod.

• wError
  has two columns, an Integer named errorCode and a Character string named errorInfo.

If an unhandled exception occurs causing node.js to exit, Omnis adds the stack traceback of the exception to the errorInfo column.

$methodreturn

$methodreturn(wReturn)

Method called with the results of a call to $callmethod.

• wReturn
  is a list/row parameter with two columns: __module and __method. If the parameter is a list, then __module and __method are only populated for the first line of the list.

If the JavaScript method returns an object, this is the Omnis equivalent of the object, created by converting the JSON to a row. If the JavaScript method returns some other data, e.g. a picture, this is a row with a single column named content, which contains the data returned by the method.

The content column for non-JSON content returned from a worker method is of type character when the content type is text/.

Example: Adding ZIP support

You could add support for ZIP files. To do this, install the node.js jszip module by running the npm command in the jsworker folder (the npm command is installed with node.js):

npm i jszip

Edit omnis_modules.js by adding an entry to the 'moduleMap' object for the zip module (or from Studio 11 it should be loaded automatically since it is in its own folder ‘omnis_zip’):

const moduleMap = {
  zip: require('./omnis_zip.js'),
  ... // Other modules
};

You can then make calls from Omnis code as follows:

Do lRow.$cols.$add("path",kCharacter,kSimplechar)
Calculate lRow.path as iZipPath
Do iJS.$callmethod("zip","loadZip",lRow,kTrue,lErrorText) Returns lOK

POP3 Worker Object

The POP3 OW3 Worker Object allows you to manage and retrieve emails stored on a POP3 Server using a background thread asynchronously, thereby giving the user full use of your app whilst carrying out the task.

The POP3 worker is similar to other OW3 workers, in that you pass an action to $init and action specific parameters, and use $run or $start to execute the request.

There is a POP3 OW3 Worker Object example in the Samples section of the Hub in the Studio Browser.

Methods

$init()

$init(cURI, cUser, cPassword, iAction [,iMessageNumber, cPostCommand])

Initialises the object so it is ready to perform the specified action using POP3. Returns true if successful

The $init parameters are:

The Actions are:

• kOW3pop3ActionStat Gets maildrop status. For a successful request, wResults has 2 columns returning the stat information, messageCount and maildropSize

• kOW3pop3ActionList Lists messages. For a successful request, wResults has a column named messageList which contains a 2 column list, with columns messageNumber and messageSize

• kOW3pop3ActionGetMessage Gets specified message. For a successful request, wResults has either a column rawData or columns headerList and mimeList (depending on the value of $splitfetchedmessage

• kOW3pop3ActionGetHeaders Gets headers for a specified message. For a successful request, wResults has either a column rawData or a column headerList (depending on the value of $splitfetchedmessage)

• kOW3pop3ActionDeleteMessage Deletes the specified message from the maildrop

• kOW3pop3ActionQuit Sends a QUIT command to the server to ensure that any messages marked for deletion are deleted

Properties

The OW3 POP3 worker has the following properties in addition to those supported by all OW3 worker objects:

CRYPTO Worker Object

The CRYPTO Worker Object allows you to perform encryption and decryption of data. The encryption types you can use include AES, Camellia, DES, and Blowfish.

The CRYPTO worker is similar to other OW3 workers, in that you pass an action to $init and action specific parameters, and use $run or $start to execute the request.

There is a CRYPTO OW3 Worker Object example in the Samples section of the Hub in the Studio Browser.

To use the worker object, create a variable with its subtype set to the CRYPTOWorker object which is contained in the OW3 Worker Objects group in the Select Object dialog, or subclass the external object. For encryption of data over 2GB you are advised to write the encrypted data to a file, rather than memory.

Methods

The CRYPTO worker has the following methods:

• $start, $run and $cancel
  Standard worker methods

• $completed and $cancelled
  Standard worker completion methods

• $makerandom
  $makerandom(iBytes,&xRandomData) generates some random data with the specified length in bytes. This is suitable for use as an encryption key or initialization vector. Returns true if successful (if an error occurs, the standard properties $errorcode and $errortext describe the error).
  iBytes is the number of bytes of random data to generate
  xRandomData is a binary variable that receives the random data

As with the other worker objects you can use the $init method with various input parameters to initialize the object, while the action can be to Encrypt or Decrypt:

• $init
  $init(iAction, iEncryptionType, iCipherMode, iPadding, xKey, xIV, vInputData [,cOutputPath]) initializes the object ready to perform the encryption or decryption. Returns true if successful

iAction can be either:

• kOW3cryptoActionEncrypt
  Encrypt the data using the specified encryption scheme and parameters

• kOW3cryptoActionDecrypt
  Decrypt the data using the specified encryption scheme and parameters

iEncryptionType can be one of:

• kOW3cryptoTypeAES
  AES encryption. Key size must be 128, 192 or 256 bits

• kOW3cryptoTypeCamellia
  Camellia encryption. Key size must be 128, 192 or 256 bits

• kOW3cryptoTypeDES
  DES encryption. Key size must be 64 or 192 bits. Uses Triple DES if key size is 192 bits

iCipherMode can be one of:

• kOW3cryptoCipherModeCBC
  CBC (Cipher Block Chaining)

• kOW3cryptoCipherModeECB
  EBC (Electronic Code Book)

• kOW3cryptoCipherModeCTR
  CTR (Counter). Not supported for kOW3cryptoTypeDES

iPadding can be one of:

• kOW3cryptoPaddingNone
  No padding (use this for cipher modes other than CBC and EBC)

• kOW3cryptoPaddingPKCS7
  PKCS7 padding

• kOW3cryptoPaddingOneAndZeros
  One and zeros padding (ISO/IEC 7816-4)

• kOW3cryptoPaddingZerosAndLen
  Pad with N-1 zero bytes followed by a byte with value N, where N is the number of padding bytes (ANSI X.923)

• kOW3cryptoPaddingZeros
  Pad with N zero bytes, where N is the number of padding bytes

Note that PKCS7 is the most common and allows binary data to be correctly decrypted, for example, kOW3cryptoPaddingZeros can lead to extra bytes being stripped from decrypted binary data.

xKey is a binary containing the key. See the encryption types for details of supported key lengths.

xIV is a binary containing the Initialization Vector (IV) (random data that can be used to make the same encrypted data different when using the same key). This must be 8 bytes long for DES and Blowfish, and 16 bytes long for AES and Camellia.

vInputData is the data to be encrypted. Either a character value which is the pathname of the file containing the data to encrypt or decrypt, or a binary variable containing the data to encrypt or decrypt.

cOutputPath is:

• Either omitted or empty meaning that the encrypted or decrypted data is supplied to $completed in the data column of the results row parameter (this column has type binary)

• Or the pathname of a file (which must not already exist) to which the worker will write the encrypted or decrypted data

The results row passed to $completed has 3 columns: errorCode, errorInfo and data. The error columns behave in the same way as the other OW3 workers: note that a negative error code is a code returned by the mbedTLS library. The data column is only used when cOutputPath was omitted when calling $init.

Properties

The CRYPTO Worker has properties as follows:

• $errorcode, $errortext, $state and $threadcount
  Standard worker properties

• $useexplicitiv
  If true, a random IV is added to the start of the data when encrypting or the first IV size bytes is removed from decrypted data. Only applies to CBC cipher mode. This means that a user can decrypt data without knowing the IV (any IV can be used for decryption, which will result in just the first IV size bytes being decrypted incorrectly, because of the way the CBC cipher mode works)

HASH Worker Object

The HASH Worker Object allows you to hash data using SHA1, SHA2, SHA3, MD5, and RIPEMD hash types, which are primarily for signature purposes, while PBKDF2 is available for password hashing.

There is a Hash OW3 Worker Object example in the Samples section of the Hub in the Studio Browser.

You use the $inithash() method to initialise the object, passing the binary or character data to be hashed, and the hash type represented by a constant, as follows:

You can use $initverifyhash to verify or compare some data against previously hashed data generated using $inithash. Having called the $init… methods, you can use $run or $start to execute the request.

To use the worker object, create a variable with its subtype set to the HASHWorker object which is contained in the OW3 Worker Objects group in the Select Object dialog, or subclass the external object.

The HASH worker object has the following methods:

• $start, $run and $cancel
  Standard worker methods: see Base Worker Methods

• $completed and $cancelled
  Standard worker completion methods: see Callback methods

• $inithash()
  $inithash(vData,iHashType,vHashParameters) initialises the object so it is ready to hash data using the specified hash type
  vData specifies the data to hash. Either binary or character. A binary value is used directly. Otherwise, for PBKDF2 the worker converts character data to UTF-8 before generating the hash. For other hash types, a character parameter is the pathname of the file containing the data to hash.
  iHashType the hash type, a kOW3hash… constant.
  vHashParameters A row of parameters that control the hash. For all types except PBKDF2, an empty row() to generate a hash, or the binary key to use when generating an HMAC (see below). For PBKDF2, a row with 3 integer columns in the order saltLength, keyLength, iterations.
  saltLength - the length of the random salt (generated by the worker). A good value for this is 16. Must be 8 to 64 inclusive
  keyLength - the length of the hashed key to be generated. A good value is 32. Must be between 16 and 256 inclusive
  iterations - the number of iterations to perform to generate the hash. A good value for iterations is at least 100000 - the higher the value, the more secure the hash, traded off against a longer execution time. Must be between 1 and 256000 inclusive

• $initverifyhash()
  $initverifyhash(vData,iHashType,vHash [,xHMACkey]) initialises the object so it is ready to generate the hash for vData using iHashType and compare it against previously generated vHash
  vData specifies the data to hash. Either binary or character. For PBKDF2 the worker converts character data to UTF-8 before generating the hash. For other hash types, a character parameter is the pathname of the file containing the data to hash.
  iHashType the hash type, a kOW3hash… constant.
  vHash A hash previously generated by the worker using $inithash(). Either binary or character. If character, the value must be the BASE64 encoded representation of the hash. Using this method, you could create a hash using $inithash and store that for future use. To verify a password or document you call $initverifyhash, with vData as the password or document to verify, and vHash as the stored hash from your call to $inithash.
  xHMACkey the key to use when verifying an HMAC authentication code (see below)

• $initsignature()
  $initsignature(vData,iHashType,vPrivateKeyPEM[,bBlind=kFalse]) initialises the object so it is ready to generate the signature for vData using iHashType and RSA encryption with private key xPrivateKeyPEM.
  vData specifies the data for which a signature is required. Either binary or character. The worker converts character data to UTF-8 before generating the signature.
  iHashType the hash type, a kOW3hash… constant.
  vPrivateKeyPEM The private key in PEM (Privacy Enhanced Mail) format. Either binary or character. Binary is assumed to already be UTF-8. The worker converts character data to UTF-8 before trying to use the private key.
  bBlind (default kFalse) If true, the RSA encryption used to generate the signature uses blinding.

HMACs

HMACs can be generated for all hash types, except PBKDF2 and the SHA3 hashes, instead of a hash. The key length for an HMAC is unrestricted (in versions prior to Studio 10.22 key length was restricted to 64 characters).

To generate an HMAC rather than a hash, supply the binary key as the hash parameters parameter of $inithash() – an empty row as this parameter generates a hash rather than HMAC. To verify an HMAC rather than a hash, supply the binary key as a new binary last parameter to $initverifyhash() – this is optional and its presence indicates HMAC.

Results

After calling one of the $init… methods, you call $run or $start. The results row passed to $completed has 3 columns: errorCode, errorInfo and data. The error columns behave in the same way as the other OW3 workers - note that a negative error code is a code returned by the mbedTLS library. The data column is only used for $inithash() and it contains the generated binary hash, provided that no error occurred – you may want to convert this to base64 before storing it, but note that if you do this you will need to convert it back to binary before using it to verify data. For $initverifyhash(), the errorCode is zero if and only if the hash was successfully verified.

The worker has properties as follows:

• $errorcode, $errortext, $state and $threadcount
  Standard worker properties

LDAP Worker Object

Lightweight Directory Access Protocol (LDAP) allows “the sharing of information about users, systems, networks, services, and applications throughout the network” (Wikipedia). The LDAP Worker is available in the OW3 group of worker objects, and is named LDAPClientWorker.

To use the LDAP Worker, you should create an Object variable or an Object Reference variable and set its subtype to the LDAPClientWorker object in the Select Object dialog; or you can create an Object class, set its superclass to the LDAPClientWorker object, create an Object variable or an Object Reference variable and set its subtype to the object class.

Properties

The LDAP Worker has all the base worker properties plus $callbackinst and $keepconnectionopen.

Methods

The LDAP Worker has all the base worker methods.

You can use the $init method to initialize the worker object to specify what information is to be returned from the LDAP server; $init for the LDAP Worker has the following definition:

$init(cURI,cUser,cPassword) 

Initializes the object so it is ready to access the specified URI using LDAP, and returns true if successful. It has the following parameters:

• cURI: The URI of the server, optionally including the URI scheme (ldap or ldaps) e.g. ldap://ldap.myserver.com. If you omit the URI scheme e.g. ldap.myserver.com, the URI scheme defaults to ldap
  cUser: The user name to be used to log on to the LDAP server
  cPassword: The password to be used to log on to the LDAP server

To structure the URI of the LDAP server, you will need to find out what parameters are required by the server; you may find the RFC4516 standard useful which defines the syntax of LDAP URLs: https://docs.ldap.com/specs/rfc4516.txt.

As $init() is called, the details of what is to be retrieved from the server are passed in the URL. You can then call $run() or $start() to run the request on the main thread or a background thread.

When the query completes, the worker calls the $completed method in the usual way for OW3 workers. The row passed to $completed has four columns:

errorCode: Zero for success, otherwise an error code

errorInfo: The description of the error

log: If you enabled logging for the OW3 worker, this contains the log

rawData: If successful, the result of the LDAP query. The developer is currently responsible for parsing this.

Python Worker Object

The Python Worker Object works exactly like the JavaScript worker, including support for HTTP/2, with a few exceptions, as follows.

When passing rows to the Python worker, a dictionary object is created in your Python module. When passing lists, a list object is created.

Installation

The Python executable is not provided with Omnis Studio, so you will have to install it manually alongside pip (the package manager) on your chosen platform. The Python worker will work with python3 only and ideally you should use at least Python 3.6. Get the latest download and installation notes for different platforms from: https://www.python.org/

On Linux and macOS, Omnis expects the binary to be in /usr/bin/python3 as well as on the PATH. On Windows, Omnis expects the installation to also be in the PATH as it relies on loading the python3.dll to get the directory where Python is installed and use the python.exe within. Currently, you cannot specify a path to a different python executable to use.

In addition, flask, psutils and requests are required; these are listed in a file called requirements.txt which is in the pyworker folder in the Omnis read/write directory. You can either install them manually or by doing:

/usr/bin/python3 -m pip install -r path/to/file/requirements.txt

Setting up a Python worker

Navigate to the writable directory of your Omnis Studio installation, typically located inside the AppData folder on Windows or the Application Support folder on macOS. On Linux, the writable and read-only directories are the same. Look for a folder named pyworker. This is where all the modules that can be used with the Python Worker will be installed.

Create a new folder inside pyworker and name it after your module. The folder's name will be used to identify your module when calling its methods through the Python Worker from Omnis Studio. For example, if your module is named test_module, create a folder named test_module inside the pyworker directory.

Inside your module's folder, you need to set up a main.py file which will be loaded by the Python Worker. The main.py file is where you can define your functions and import other packages - the Python Worker will automatically load this file and you can call the methods from Omnis Studio. For example, you can create a test function in main.py in the following way:

from omnis_calls import sendResponse, sendError

def test(param):
    return sendResponse({'unicode': 'Fingerspitzengef\xFChl is a German term.\nIt\u2019s pronounced as follows: [\u02C8f\u026A\u014B\u0250\u02CC\u0283p\u026Ats\u0259n\u0261\u0259\u02CCfy\u02D0l]'})

Calling Python methods

Create a new object variable and inherit from the Python Worker, grouped under the OW3 Worker Objects in the Select Object dialog. For more control, you might prefer to create a new object class in your library and inherit from the Python worker through the $superclass property.

Once you have an object or an object reference to the Python Worker, you need initialize and then start the worker:

Do pyWorker.$init(,'/path/to/python3')
Do pyWorker.$start() Returns #F

A new thread will be launched upon calling $start where the Python process will wait until you give it methods to execute. Furthermore, you only need to call $start as you can make multiple method calls to the same worker.

The first parameter to $init takes the search path, which is usually best to leave as the default. The second parameter however is very useful: you can use it to specify the exact Python executable you wish to use. Please note whichever Python executable you try to use, it will need to have the packages from the requirements file installed, otherwise it will fail to start.

If the second parameter to $init is omitted, the default will be /usr/bin/python3 on Linux and macOS. On Windows, Omnis attempts to load the python3.dll which works if it's available in the PATH, then will try loading the python3.exe in the same directory as the python3.dll.

To avoid failures when starting the Python Worker, you are advised to point the Worker to your python3 executable through the second parameter to $init.

If your Python worker has started successfully, you can use $callmethod(cModule, cMethod) where cModule is the name of the module you wish to use and cMethod is the name of the method inside your module you want to execute:

Do pyWorker.$callmethod('omnis_test', 'test') Returns #F

Parameters passed to the Python worker are in the form of a list or row. You can pass the list or row in the $callmethod:

Do lRow.$cols.$add('message',kCharacter,kSimplechar)
Do lRow.$assigncols('hello world')
Do pyWorker.$callmethod("omnis_test","test",lRow) Returns #F

In order to access parameters on the Python module side, use the param parameter of your method (in main.py):

from omnis_calls import sendResponse, sendError

def test(param):
    return sendResponse(param['value'])

Note Omnis rows will create a Python dictionary param and Omnis lists will create a Python list param.

When the Python Worker returns, the $methodreturn callback is called with a row parameter. Inside the row parameter, you can find the returned data from your method as well as any tags supplied to $callmethod. For example, calling the test method in the omnis_test module will result in Unicode characters to be returned inside the unicode column in the first row parameter of $methodreturn.

If you have called a Python method but wish to cancel it, use the $cancel method on the Python worker:

Do pyWorker.$cancel()

Cancelling a call might be useful if you think it has been running for too long and wish to stop it.

The $callmethod is asynchronous by default, but there might be times where you wish to block the main thread until the Python Worker finishes its job, in which case you can pass kTrue to the bWait parameter of $callmethod (4th parameter):

Do pyWorker.$callmethod('omnis_test','test',,kTrue) Returns #F

The same Python Worker instance can be used for multiple method calls since Python methods can be made asynchronous, as such it may be useful to tag each call with an identifiable number. The 6th parameter of $callmethod can accept a tag which will be returned in the $methodreturn:

Do pyWorker.$callmethod('omnis_test','test',,,,lTagID) Returns #F

A __tag column is added to the row parameter of $methodreturn if a tag was given to $callmethod, allowing you to identify the results.

Error handling

If your Python method throws errors when executing, the $methoderror callback is called with a row parameter which contains two columns which you can use to debug your Python method:

• errorCode column contains the error code of the error.

• errorInfo column contains information about the error.

If the Python Worker has failed to start, the $workererror callback is called with a row parameter which contains two columns:

• errorCode column contains the error code of the error.

• errorInfo column contains information about the error.

These errors are unlikely to be caused by the method called, but more likely issues with Python itself, e.g. quitting due to missing packages.

If you inherited your Python Worker, you can simply override callbacks in your new object. Otherwise, if you created a new variable with the object type of OW3 Python Worker, you will need to register the instance that will receive the callbacks such as $methoderror, $workererror, and $methodreturn. You can do this by assigning the instance to the $callbackinst property, for example:

Do pyWorker.$callbackinst.$assign($cinst)

This will assign the callback instance to $cinst (current instance). If $cinst is a window, then that window class must implement the methods $methoderror, $workererror, and $methodreturn.

$init([cPath,cExecutable,bDebugWorker,cJvmOptions])

...
   <dependencies>
      <dependency>
         <groupId>net.omnis</groupId>
         <artifactId>OmnisCalls</artifactId>
         <version>0.1</version>
         <scope>system</scope>
         <systemPath>path/to/OmnisCalls.jar</systemPath>
      </dependency>
   </dependencies>
...

...
   <build>
      <plugins>
         <!-- Get dependencies in lib folder -->
         <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-dependency-plugin</artifactId>
            <version>3.2.0</version>
            <executions>
               <execution>
                  <id>copy-dependencies</id>
                  <phase>package</phase>
                  <goals>
                     <goal>copy-dependencies</goal>
                  </goals>
                  <configuration>
                     <outputDirectory>
                        ${project.build.directory}/lib
                     </outputDirectory>
                  </configuration>
               </execution>
            </executions>
         </plugin>
      </plugins>
   </build>
...

   package net.omnis.OmnisTest; import net.omnis.OmnisCalls.*;
   public class Test extends OModule {
      // Implement your methods here
   }

   public Response test(Map<String, Object> pParams) {

      Map<String, Object> data = new HashMap<>(); data.put("unicode",
         "Fingerspitzengef\u00FChl is a German term.\nIt\u2019s pronounced as follows:       [\u02C8f\u026A\u014B\u0250\u02CC\u0283p\u026Ats\u0259n\u0261\u0259\u02CCfy
\u02D0l]");

      return new SendResponse(data);
   }

   package net.omnis.OmnisTest; 
   import net.omnis.OmnisCalls.*; 

   import java.util.Map;
   import java.util.HashMap; 
   import java.util.ArrayList;

   public class Test extends OModule {

      public Response test(Map<String, Object> pParams) {

         Map<String, Object> data = new HashMap<>(); data.put("unicode","Fingerspitzengef\u00FChl is a German term.\nIt\u2019s 
         pronounced as follows: [\u02C8f\u026A\u014B\u0250\u02CC\u0283p\u026Ats\u0259n\u0261\u0259\u02CCfy\u02D0l]");

         ArrayList<String> listData = new ArrayList<>(); 
         listData.add("Python"); 
         listData.add("JavaScript"); 
         listData.add("Java");
         listData.add(".NET Core"); 

         data.put("OW3 Workers", listData);

         return new SendResponse(data);
      }
   }

Web Worker Objects

The following section refers to the Web Worker Objects (OWEB) available in Omnis Studio prior to Studio 8.1 (introduced in Studio 6.1.2): note they require Java to be installed and are therefore no longer supported in Studio 10.x or above: you should use the OW3 Workers for all new development.

SMTP Client Workers

The SMTP worker object allows you to submit email(s) to an SMTP server in a background thread, working in a similar way to the existing “worker objects” for DAMs, HTTP and Timers. In addition, it provides support for authentication methods not supported by the existing SMTPSend command including DIGEST-MD5, NTLM and OAUTH2.

In addition to the SMTP worker object, there is an object called EMAILMessage, which you use to build the message to be sent by the worker.

Software Requirements

The SMTP worker object relies on Java, and therefore relies on some Java files located in the ‘java/axis/lib’ folder in the main Omnis Studio folder: see the Java Objects chapter for details about running Java in Omnis.

EMAILMessage Object

The EMAILMessage object is used to construct the message to be sent to the SMTP Client worker. The EMAILMessage object has methods to manipulate the MIME body parts of the message. Each body part has a non-zero integer identifier that uniquely identifies the body part within the context of the object instance. EMAILmessage needs to remain in scope until the worker $completed or $cancelled message is called.

Note: If you specify a charset of kUniTypeAuto for binary or file body parts, the object will inspect the data, and set its charset according to the presence of a BOM (Byte Order Marker) to kUniTypeUTF8, kUniTypeUTF16BE, kUniTypeUTF16LE, kUniTypeUTF32BE or kUniTypeUTF32LE. If there is no BOM, the charset will be kUniTypeNativeCharacters, resulting in iso-8859-1 for Linux, macintosh for macOS or windows-1252 for Windows.

Methods

$createbodypartfromfile

$createbodypartfromfile(cPath[,cMIMEType,iCharset,cEncoding,cDisposition,cFilename])

Creates a MIME file body part. Returns non-zero integer body part id (unique for this EMAILMessage object) or zero if an error occurs.

$createbodypartfromchar

$createbodypartfromchar(cData[,cMIMEType,iCharset,cEncoding,cDisposition,cFilename])

Creates a MIME body part from character data. Returns non-zero integer body part id (unique for this EMAILMessage object) or zero if an error occurs.

$createbodypartfrombin

$createbodypartfrombin(xBin[,cMIMEType,iCharset,cEncoding,cDisposition,cFilename])

Creates a MIME body part from binary data. Returns non-zero integer body part id (unique for this EMAILMessage object) or zero if an error occurs.

$createbodypartfromparts

$createbodypartfromparts(cMultiType,vPart[,iPart2,...])

Creates a MIME multi-part body part containing specified body parts. Returns non-zero integer body part id (unique for this EMAILMessage object) or zero if an error occurs.

Note that each body part can only be used once in a multi-part body.

$deleteaallbodyparts

$deleteaallbodyparts()

Deletes all body parts that have been created using a $createbodypart... method. Also sets property $contentid to zero.

Properties

The EMAILMessage object has the following properties:

Constants

The EMAILMessage object has the following constants:

SMTPClientWorker Object

The SMTPClientWorker object uses the standard worker mechanism, with methods $init, $start, $run and $cancel, and callbacks $completed and $cancelled. In addition, there are some properties which further control the behavior of the object.

Methods

$init

$init(zMessage,cServer[,iSecure=kOWEBsmtpSecureNotSecure,iAuthType=kOWEBsmtpAuthTypeNone,cUser,cPassword,cOAUTH2,cRealm,cNTLMDomain,lProps, bMailShot=kFalse ])

Initialize the worker object so it is ready to send message oMessage. Returns true if successful.

$run

$run([cOAUTH2authCode])

Runs the worker on current thread. Returns true if the worker executed successfully. The cOAUTH2authCode parameter is discussed in the section on OAUTH2. It is not required in the initial call to $run to send an email.

$start

$start([cOAUTH2authCode])

Runs the worker on background thread. Returns true if the worker was successfully started. The cOAUTH2authCode parameter is discussed in the section on OAUTH2. It is not required in the initial call to $start to send an email.

$cancel

$cancel()

If required,cancels execution of worker on background thread. Will not return until the request has been cancelled.

$completed

$completed(wResults)

Callback method called when the request completes. Typically, you would subclass the SMTPClientWorker, and override $completed in order to receive the results. wResults is a row containing the results of executing the request. It has columns as follows:

$cancelled

$cancelled()

Callback method called when the request has been cancelled by a call to $cancel(). Typically, you would subclass the SMTPClientWorker, and override $cancelled.

Properties

The SMTPClientWorker object has the following properties:

Constants

Authentication Types

These constants can be added together in order to form a bit mask of allowed authentication types:

Secure Connection Type

These constants indicate how the connection is to be made secure:

OAUTH2

This section provides an overview of OAUTH2, including some key terms.

OAUTH2 provides a way for applications to perform actions on behalf of a user, provided that they have the permission of the user. So in the case of the SMTPClientWorker, when using OAUTH2 authentication, the Omnis Studio client needs to be given permission to send the email.

This all occurs in the context of an OAUTH2 authority, so for example if you are using GMAIL, the OAUTH2 authority is Google, or if you are using Windows mail, the OAUTH2 authority is Microsoft. he client application (Omnis Studio or more typically your application) needs to be registered as an application with the OAUTH2 authority; this gives it two key pieces of information:

• Client ID. A unique identifier for the client application.

• Client secret. A string used in requests to the OAUTH2 authority

that authenticates the application. This needs to be kept as private as possible.

How you register your application with the OAUTH2 authority depends on the particular authority. For example:

• For Google
  go to the Google Developers Console (https://console.developers.google.com) and create a new project. On the credentials screen, create a new client ID for an installed application of type other.

• For Microsoft
  go to the Microsoft account Developer centre (https://account.live.com/developers/applications/) and create an application.
  In the API Settings make sure “Mobile or desktop client app” is set to Yes.

The user interfaces for these developer consoles allow you to obtain the client ID and client secret.

In order to use OAUTH2 authentication, the application needs to supply an OAUTH2 access token as the password. An access token is a short-lived password that is typically valid for an hour. The first time the application needs an access token, there has to be some interaction at the user interface:

• The application opens a browser window at the OAUTH2 authorisation code URL for the authority. Note that this URL includes a scope which indicates what type of permission is being requested. Each authority has a scope value which indicates that the user wants to manage email.

• The browser window may ask the user to log on to their account with the relevant authority. Once logged on, it will ask the user if they give the particular application permission to use their email. If the user agrees, the browser redirects to a URI called the redirect URI, passing an authorisation code to the URI. There are special redirect URIs for OAUTH2 authorities which cause the authorisation code to be available in the browser window after the user agrees - you need to use these special redirect URIs to use the SMTPClientWorker.

• The user copies the authorisation code from the browser window, and pastes it into the application.

• The application uses the authorisation code, client secret, client id and redirect URI to make an HTTP request to the token URL. A successful call to this URL returns an access token, expiry information for the access token (how long it is valid) and a refresh token.

• The application uses the access token as the password.

As part of the process described above, the application stores the access token, expiry information, and refresh token in permanent storage. The next time the application needs to log on, the application reads this information. If the access token is probably still valid, based on the expiry information, the application uses it. If not, the application uses the refresh token to make a slightly different request to the token URL, in order to get a new access token, which it then stores and uses to log on. Note:

• If the log on fails using the saved access token (with an authentication failure), the application will then try to use the refresh token to obtain a new access token.

• The refresh token may be invalidated by the authority at some point. For this, and various other reasons, log on may fail with an authentication failure. In that case, the application needs to return to the initial step of opening the browser window at the OAUTH2 authorisation code URL, so that it can obtain the user’s permission, and a new access token and refresh token.

OAUTH2 for SMTPClientWorker

This section describes how the OAUTH2 support for the SMTPClientWorker works.

Authority Configuration

Each authority has a folder with the authority name in the folder secure/oauth2/smtp, in the Omnis data folder. In the installed tree, there are folders for two authorities, and each folder includes a file called config.json; this is a JSON file that configures the authority for use with the SMTPClientWorker. The installed authorities, and their JSON files, are:

gmail:
{
  "authURL": "https://accounts.google.com/o/oauth2/auth",
  "tokenURL": "https://www.googleapis.com/oauth2/v3/token",
  "proxyServer": "",
  "scope": "http://mail.google.com/",
  "redirectURI": "urn:ietf:wg:oauth:2.0:oob",
  "clientID": "",
  "clientSecret": ""
}

outlook:
{
  "authURL": "https://login.live.com/oauth20_authorize.srf",
  "tokenURL": "https://login.live.com/oauth20_token.srf",
  "proxyServer": "",
  "scope": "wl.imap,wl.offline_access",
  "redirectURI": "https://login.live.com/oauth20_desktop.srf",
  "clientID": "",
  "clientSecret": ""
}

When using these authorities, you need to supply your client ID. You can optionally store your client secret here, or if you want to keep it in another more secure location, you can store it how you like, and then supply it to the SMTPClientWorker using the $clientsecret property.

The proxyServer only requires a value if your client system is using a proxy server; the SMTPClientWorker uses this when making HTTP requests to the token URL.

User Storage

The SMTPClientWorker stores the access token, expiry information, and refresh token for a user in the file <user>.info in the authority folder, where <user> is typically the email address of the authorising user. This file is a JSON file, that is automatically handled by the SMTPClientWorker, so you should not need to edit this file.

Application Logic

After you have configured the authority, to use OAUTH2 in your application with the SMTPClientWorker, there is only one additional step you need to code in your application. Essentially, this comprises:

• Opening a browser window at the OAUTH2 authorisation code URL.

• Accepting the pasted authorisation code.

• Calling $run or $start for a second time, this time also passing the authorisation code.

For example, in $completed:

If pResults.errorCode=kOWEBsmtpErrorOAUTH2authCodeRequired

  OK message {A browser window will open so that you can   authorize sending email.//Please follow the instructions and   then paste the authorization code into the following dialog...}

  Launch program ,[pResults.oauth2_authcodeurl]

  While  len(lAuthCode)=0
    Prompt for input Authorization code Returns lAuthCode (Cancel button)
    If flag false 
      Yes/No message {Are you sure you want to cancel?}
      If flag true 
        Quit method 
      End If 
    End If 
  End While 
  Do $cinst.$start(lAuthCode)
End If 

External Commands

Note the Web and Email external commands are obsolete and are no longer supported in Studio 10.x or above: you should use the OW3 Workers for all new development.

The following protocols were supported: HTTP, FTP, SMTP, POP3, and IMAP. The external commands are prefixed with the respective protocol name, e.g. HTTPSend, FTPConnect, etc.

The Web and Email external commands are not displayed in the Code Editor since the Exclude Old Commands filter is selected in the Code Editor (if you select No Filter from the Modify menu they will be available); these commands are described in the Command Reference in the External commands group and in the Omnis Help (press F1) under the External commands group.

Multi-threading

The Web and Email external commands are multi-threaded, when running on a multi-threaded Omnis Server. The Web commands allow another thread to execute in the multi-threaded server while the current command runs. Note that the same socket cannot safely be used concurrently by more than one thread. See also the ‘SMTP Client Workers’ section for using email in multi-threaded environment.

MailSplit

If the encoding cannot be determined from the MIME, MailSplit uses $importencoding as the default encoding rather than UTF-8, provided that $importencoding is an 8 bit encoding, that is, anything except kUniTypeUTF16, kUniTypeUTF16BE and kUniTypeUTF16LE.

Email Headers

The SMTPSend and MailSplit commands support international characters in email headers (using RFC2047). The character limit of 76 for RFC2047 encoded words for mail headers has been removed in the MailSplit command.

SSL Security

The Web and Email external commands allow support for secure connections using Secure Sockets Layer (SSL) technology. However, Transport Layer Security (TLS) supersedes SSL and should be used in new development. Applications that require a high level of interoperability should support SSL 3.0 and TLS.

The HTTP, FTP, SMTP, POP3, and IMAP client commands that establish a connection to a server allow you to control if and how a secure connection is used. The commands which allow secure connections are:

The parameters Secure and Verify allow you to enable support for secure connections. The parameters behave as follows:

• Secure
  is an optional Boolean* parameter which indicates if a secure connection is required to the server. Pass kFalse for non-secure (the default). Pass kTrue (value 1) for a secure connection; this enables the Verify option.
  *In addition, you can pass value 2 to some of the commands to enable specific types of authentication. The SSL package installed on yours or the client’s system is used (Windows: Schannel, or macOS: Secure Transport). FTPS resumes the TLS session for data connections. In addition, it automatically sends PBSZ and PROT commands to the server after establishing a secure control connection

• Verify
  is an optional Boolean parameter which is only significant when Secure is not kFalse. When Verify is kTrue, the command instructs the SSL package to verify the server's identity using its certificate; if the verification fails, the connection will not be established. You can pass Verify as kFalse, to turn off the verification; in this case, the connection will still be encrypted, but there is a chance the server is an impostor.

For example, the FTPConnect command allows you to establish a secure connection to the specified FTP server; the full syntax of the command is:

FTPConnect (serveraddr, username, password [,port, errorprotocoltext, secure {Default zero insecure;1 secure;2 use AUTH TLS}, verify {Default kTrue}]) Returns socket

where Secure is an optional Boolean parameter which indicates if a secure connection is required to the server. Pass kTrue for a secure connection. If you pass secure with the value 2, the connection is initially not secure, but after the initial exchange with the server, FTPConnect issues an AUTH TLS FTP command to make the connection secure if the server supports it (see RFC 4217 for details), followed by further commands necessary to set up the secure connection. Authentication occurs after a successful AUTH TLS command. Note that if you use either of the secure options, all data connections are also secure, and all data transfer uses passive FTP.

When set to true (the default), the "ftpsresumesession" item in the "web" section of the config.json file ensures that the FTP commands attempt to resume the control connection session when establishing a secure data connection.

HTTPPage

The HTTPPage command has an additional parameter to allow you to ignore SSL. The full syntax of the command is:

HTTPPage (url[,Service|Port,pVerify]) Returns html-text

When passed as false, the pVerify argument prevents SSL verification when using a secure URL, so you can use:

HTTPPage (url,,kFalse)

SSL Packages

In order to use SSL or TLS in the Web and Email external commands the Secure Channel (Schannel) package on Windows, or Secure Transport on macOS must be installed on your development computer or a client’s computer: these are present by default on their respective platforms.

OpenSSL

Existing Users should note: The Web and Email external commands relied on OpenSSL in previous versions to provide secure communications. Support for OpenSSL has been removed for these commands and support for SSL and TLS relies on the built-in security for each platform.

If you have used OpenSSL to provide secure comms for these commands in existing applications, you will need to switch to using either Schannel or Secure Transport depending on what platform your app is running on.

Certificate Authority Certificates

In order to perform the verification (when the Verify parameter is kTrue), the SSL package uses the Certificate Authority Certificates in the cacerts sub-folder of the secure folder in the Omnis folder. If you use your own Certificate Authority to self-sign certificates, you can place its certificate in the cacerts folder, and the SSL package will use it after you restart Omnis.

Web Command Error Codes

Error codes for the Web Commands are listed in the Commands Reference.