Main Content

restFunctionConnector

MATLAB to client application connection

Since R2024a

expand all in page

    Description

    The RESTFunctionConnector object manages communication between MATLAB® and a client application. Get this object from the machine that has your licensed MATLAB. You can use the connector object to open and close the port on the user machine, write the communication logs, handle certificates, generate URL endpoints, accept client requests, and relay responses.

    To use a simple function service, create and start a RESTFunctionService object.

    Creation

    Syntax

    conn = restFunctionConnector

    Description

    conn = restFunctionConnector gets the existing RESTFunctionConnector object. Call the function on the machine that has your licensed MATLAB.

    example

    Properties

    expand all

    User machine port that receives client requests and sends responses, specified as a double , in the range between [1025, 65535]. This value is used in the BaseUrl endpoint.

    Log folder where service logs are written, specified as a string scalar. For information about <mwPath>, see Pathname Displays <mwPath>.

    Example: "C:\Users\<username>\AppData\Local\MathWorks\restfcnconnector\logs"

    Hostname or IP address, specified as a string scalar. This value is used in the BaseUrl endpoint.

    Example: "localhost"

    Since R2024b

    When to restart connector service, specified as [] or as an integer between [0, 23] where 0 corresponds to 12 midnight and 23 corresponds to 11 pm. If you specify [], the connector restarts when an update is available.

    MATLAB REST function services rely on the MathWorks® Service Host (MSH) for communication with MATLAB from client applications. MSH regularly releases updates and restarts automatically after updates are installed. If services are running before the update, the REST function connector stops during the update and then automatically restarts, along with the running services, when the MSH is available. Any computations or requests made by your program during the update cannot be recovered. If you have long-running function calls, you can use the PreferredRestartHour property to set the preferred time for restarting the MSH to avoid interruption of your workflow.

    You cannot edit the PreferredRestartHour property:

    • After you start the connector. To set PreferredRestartHour, the Status property value must be notrunning.

    • If an MSH update is already downloaded. Wait until MSH restarts, then set PreferredRestartHour.

    For more information, see MathWorks Service Host Updates.

    Example: conn.PreferredRestartHour = 0 sets the preferred restart time to midnight.

    Example: conn.PreferredRestartHour = [] sets the restart time to when an update is available

    Access mode, specified as "local" or "remote". Use this property to control whether local or remote clients can access the function connector.

    Example: ClientAccessMode="remote"

    This property is read-only.

    Names of the running function services registered with the function connector, returned as a string vector. To register a service, call the start function on a RESTFunctionService object.

    This property is read-only.

    Client request token, returned as a string scalar. The connector object uses this token to authenticate client requests. Use this value in the client request HTTP header field mwRESTPersonalAccessToken. Requests without a token or with an invalid token are declined.

    Example: "AQIDBAUGBwgJCgsMDQ4PEBESExQVFhcYGRobHB0eHyA="

    This property is read-only.

    Expiration date of the client request token, returned as a datetime scalar in dd-mm-yyyy format. The default lifetime of a token is 30 days.

    Example: 05-Dec-2024

    This property is read-only.

    Certificate pathname, returned as a string scalar. Client applications use this certificate (.pem) file to make requests to the connector over HTTPS. Copy this certificate to your client application.

    Example: "C:\Users\<username>\AppData\Local\MathWorks\restfcnconnector\publickey.pem"

    This property is read-only.

    Expiration date of the certificate, returned as a datetime scalar in dd-mm-yyyy format.

    Example: 15-Dec-2024

    This property is read-only.

    URL endpoint for listening for and making requests from client applications over HTTPS, returned as a string scalar.

    Example: "https://localhost:9920/matlab/feval/v1/EL"

    This property is read-only.

    Service status, returned as notrunning or running. This property indicates whether the service has been started and can receive client requests.

    Object Functions

    startStart REST function connector from MATLAB
    stopStop REST function connector from MATLAB
    changeTokenChange token of REST function connector
    changeCertificateChange certificate of REST function connector
    resetRestore properties of RESTFunctionConnector to default values

    Examples

    collapse all

    A RESTFunctionConnector manages communication between MATLAB and client applications.

    Get connector conn in your MATLAB application. The TokenExpirationDate value indicates that you obtained the connector on September 20, 2024.

    conn = restFunctionConnector
    conn =  
  RESTFunctionConnector with properties: 
 
                             Port: 9920 
                      LogLocation: "<mwPath>\restfcnconnector\logs" 
                         HostName: "" 
                 ClientAccessMode: local 
                     ServiceNames: 1x0 string 
          RESTPersonalAccessToken: "AQIDBAUGBwgJCgsMDQ4PEBESExQVFhcYGRobHB0eHyA=" 
              TokenExpirationDate: 20-Oct-2024 
                      Certificate: "<mwPath>\restfcnconnector\publickey.pem"
        CertificateExpirationDate: [0×0 datetime]
                          BaseURL: ""
                           Status: notrunning

    First, get a REST function connector.

    conn = restFunctionConnector;
conn.ClientAccessMode = remote;

    Stop the existing connection.

    stop(conn);

    Generate a new personal access token, specifying its valid timespan as 45 days. The TokenExpirationDate value indicates that you made the change 45 days earlier, on October 20, 2023.

    changeToken(conn,45);
conn
    conn = 
  RESTFunctionConnector with properties: 
 
                             Port: 9920 
                      LogLocation: "<mwPath>\restfcnconnector\logs" 
                         HostName: "" 
                 ClientAccessMode: remote 
                     ServiceNames: 1x0 string 
          RESTPersonalAccessToken: "QADIABUGwBgJCgsMDQ4PEBESExQVFhcYGRobHB0eBcD=" 
              TokenExpirationDate: 04-Dec-2023 
                      Certificate: "<mwPath>\restfcnconnector\publickey.pem" 
        CertificateExpirationDate: 20-Sep-2023 
                          BaseUrl: "" 
                           Status: notrunning

    More About

    expand all

    Version History

    Introduced in R2024a

    expand all

    See Also

    Objects