| Customize Help

Fundamentals for creating your MILweb client application


This section discusses how to create a MILweb application, using either the JavaScript or C/C++ API. For additional information specific to each language (including their respective function references), see the Creating a MILweb client application with JavaScript section later in this chapter and the Creating a MILweb client application with C/C++ section later in this chapter.

MILweb uses a client-server architecture. Your MILweb client application connects to your MILweb server application and requests data about a published MIL object. Your MILweb server application accepts the request and sends data about the object back to the client. You can also send custom data between the client and server using MIL messages.

Conventions for referring to MILweb functions and constants

The following conventions for referring to MILweb functions and constants are used in this chapter:

  • MilWeb.FunctionName. A function in the MILweb API. If a language is not specified, this refers to a function that is available in both JavaScript and C/C++.

    For JavaScript, you use the name MilWeb.FunctionName to call the function. For C, you use MilWebFunctionName. For C++, you use MilWeb::FunctionName (or use the namespace MilWeb).

    If a function exists in both the JavaScript and C/C++ MILweb API, a link is provided to the JavaScript version of the function.

  • MilWeb.M_CONSTANT_NAME. A constant in the MILweb API. If a language is not specified, this refers to a constant that is available in both JavaScript and C/C++.

    For JavaScript, the name of the constant is MilWeb.M_CONSTANT_NAME. For C/C++, you do not include the MilWeb prefix (just use M_CONSTANT_NAME).

MILweb allocations and functions

There are no mandatory allocations for a MILweb client application. One MILweb client application can connect to multiple MILweb servers; you do not allocate a separate application context for each one. However, you must connect to the MILweb server using MilWeb.MappOpenConnection. This function returns the client-side MIL identifier of the MILweb server.

You use the client-side MIL identifier of a connected MILweb server application, or that of a MIL object published by the application, to specify with which MILweb server application a function will interact. This is similar to most MIL functions, for which you must specify the MIL identifier of either a system or an object that was allocated on that system. Just as specifying the identifier of a MIL object (such as a digitizer) allocated on a particular system implicitly specifies to use that system, specifying the client-side identifier of a MIL object (such as a display) allocated in a MILweb server application implicitly specifies to interact with that MILweb server application.

Most MILweb functions interact with the connected MILweb server in some way. These functions will return an error if the MILweb client is not connected to the MILweb server. You should not use any MILweb functions except MilWeb.MappOpenConnection and MilWeb.MappHookFunction until your MILweb client is connected to a MILweb server.

Publishing MIL objects

Before your MILweb client application can access a MIL object, you must publish the object in your MILweb server application. To do so, use MobjControl() with M_WEB_PUBLISH and M_READ_ONLY or M_READ_WRITE. You must also assign a name to the object using MobjControl() with M_OBJECT_NAME.

In your MILweb client application, to learn the client-side MIL identifier of the published object use MilWeb.MappInquireConnection with MilWeb.M_WEB_PUBLISHED_NAME and the name you assigned to the object. You can use this client-side identifier to access the object, with appropriate functions.

Note that for JavaScript, you cannot use the client-side MIL identifier immediately after inquiring it; you must hook a function to be executed when the connection to the server or object has been established (which happens asynchronously). For more information, see the Accessing MILweb server applications and published MIL objects subsection of the Creating a MILweb client application with JavaScript section later in this chapter.

The only MIL objects that can be published are MILweb displays and message mailboxes.

You use client-side MIL identifiers in your MILweb client applications, to identify both your MILweb server and the MIL objects it has published. However, the literal value of the client-side identifier assigned to a particular MILweb server or MIL object is not the same for each instance of your MILweb client. Therefore, you must seperately inquire the client-side identifier of a MIL object in each instance of your MILweb client (using MilWeb.MappInquireConnection with MilWeb.M_WEB_PUBLISHED_NAME ).

Connecting to a MILweb server application

The following steps provide a typical methodology to establish a connection between your MILweb client and MILweb server:

  1. In your MIL application, enable MILweb using MappControl() with M_WEB_CONNECTION. Your MIL application is now a MILweb server application.

    MILweb servers are intended to be run on a segmented LAN that has no internet/WAN access; MILweb servers offer no internal security mechanisms. When MILweb is enabled, you should typically ensure that your network administrator configures your network to prevent incoming connections from the internet/WAN to the computer running your MIL application (and from any other devices on your network that do not need access). If this is not possible, at a minimum you should block incoming connections from the internet to the listening port of the MILweb server. You can inquire which port is used for this purpose, using MappInquire() with M_WEB_CONNECTION_PORT.

  2. Optionally, specify the listening port on which the MILweb server application receives incoming connections, using MappControl() with M_WEB_CONNECTION_PORT. This must be a port not used by any other application running on the computer. The default port is 7861.

  3. In your MILweb client application, open a connection to your MIL application using MilWeb.MappOpenConnection with the URL of the computer running your MILweb server application.

    This function writes (to the object or variable specified by the UserVarPtr or RemoteContextAppIdPtr parameter) the client-side MIL application identifier that you use with some other MILweb functions, such as MilWeb.MappInquireConnection. For JavaScript, the connection is completed asynchronously after MilWeb.MappOpenConnection has returned; you therefore cannot use the client-side identifier until the connection is established. A MilWeb.M_CONNECT event is generated when the connection is established.

    The URL is ws://, followed by the domain name or local static IP address of the computer running the MILweb server, and a colon (for example, ws://192.168.1.58: or ws://VisionController42:).

    If you changed the MILweb listening port, or there is more than one MILweb server application running on the same computer, you must append to the URL a colon (:) followed by the listening port. For example, ws://192.168.1.58:7861.

    On the computer running the MILweb server, you can always use localhost instead of the IP address or domain name.

  4. For JavaScript only, in your MILweb client application, hook a function to new connection events using MilWeb.MappHookFunction with MilWeb.M_CONNECT and the client-side application identifier that was written by MilWeb.MappInquireConnection. When the hooked function is called, the connection has been established and you can use the client-side application identifier with other functions in your application. You might find it useful to set a global Boolean variable within the hooked function as a flag to indicate that the connection has been established.

    Since the connection to the MILweb server application is made asynchronously (after the call to MilWeb.MappOpenConnection has returned and execution of your code has continued), the hook-handler function will be called when the connection is established (as long as MilWeb.MappHookFunction immediately follows MilWeb.MappOpenConnection).

    This does not apply to C/C++; MilWeb::MappOpenConnection does not return until after the connection has been established. The client-side application identifier can therefore be used immediately.

MILweb displays

You can send the contents of a MIL 2D display to one or more MILweb clients, if the display was allocated with M_WEB and was published (as described in the Publishing MIL objects subsection of this section). All connected MILweb clients showing the display receive the same image information; if the MILweb server or a connected instance of the MILweb client modifies the display (for example, using MilWeb.MdispZoom or interactive keyboard controls), the display is modified for all instances of the MILweb client showing that display. To give each instance of your MILweb client an independent display, you must allocate multiple displays.

You cannot show a MIL 3D display in a MILweb client. You cannot show a MILweb display in your MILweb server application.

The following steps provide a typical methodology to present a display from your MILweb server application in a connected MILweb client application:

  1. In your MILweb server application, allocate a MILweb display using MdispAlloc() with M_WEB.

  2. In your MILweb server application, assign a unique name to this display using MobjControl() with M_OBJECT_NAME.

  3. In your MILweb server application, publish the display using MobjControl() with M_WEB_PUBLISH and either M_READ_ONLY or M_READ_WRITE (for displays, there is no difference between these settings).

  4. In your MILweb server application, select an image to the display using MdispSelect().

  5. In your MILweb client application, retrieve the MIL identifier of the display using MilWeb.MappInquireConnection with MilWeb.M_WEB_PUBLISHED_NAME and the name you assigned to the display.

  6. Present the display in your MILweb client application. To do so:

    • For JavaScript, create an HTML5 canvas element in your HTML file and present the display in that canvas using MilWeb.MdispSelectWindow. For example, you can create an HTML5 canvas element by including the following in your HTML file:

      <canvas id="PlaceToShowAMILDisplay" width="1600" height="900"></canvas>

      Use MilWeb.MdispSelectWindow with the canvas id that you set, and the client-side MIL identifier of the display. The display will be automatically presented in the HTML5 canvas.

    • For C/C++, the output of the display is automatically transmitted to the MILweb client as a bitmap image (including annotations). To display it, you must map a bitmap data structure appropriate for the third-party GUI toolkit that you are using (for example, Windows GDI (win32), Qt, or GTK) onto the image data. For more information, see the Presenting a display subsection of the Creating a MILweb client application with C/C++ section later in this chapter.

  7. Optionally, control the display in your MILweb server application (using functions in the Mdisp module) or in your MILweb client application (using functions in the MilWeb.Mdisp) module. MILweb displays support most of the same functionality as windowed displays.

    The MILweb API only provides a subset of the functionality of the full Mdisp module. To perform tasks not supported by the MILweb API, you must use the standard MIL display functions in your MILweb server application. For example, to associate the display with a 2D graphics list, use MdispControl(). To associate the display with a LUT, use MdispLut() in your MILweb server application.

Size of a MILweb display

A MILweb display is always the same size as the currently selected image buffer. The visible content of a MILweb display is transmitted to the MILweb client as bitmap image data after panning, zooming, annotations, and other settings/transformations are applied. Any data outside the visible area of the MILweb display is not transmitted to the MILweb client.

For example, if you present the display in an HTML5 canvas using MilWeb.MdispSelectWindow (only available for JavaScript), and the HTML5 canvas is larger than the selected image buffer, the display is presented in an area the size of the image buffer. If you scale the displayed image using MilWeb.MdispZoom (equivalent to using MdispZoom() directly in the MILweb server application), the size of the presented display does not change; it remains the same size as the image buffer, but shows only the zoomed region of the image.

Interacting with a display

You can allow a user to interactively control a display through your MILweb client application, as though they were interacting with a windowed display shown on the computer running your MILweb server application. To do so, in your MILweb client application, use MilWeb.MdispControl with MilWeb.M_INTERACTIVE and MilWeb.M_ENABLE. If the display is annotated by a 2D graphics list that has been made editable (using MgraControl() with M_EDITABLE), the user is also able to edit those annotations interactively. For more information, see the Creating and modifying graphics interactively section of Chapter 24: Generating graphics.

You can also simulate user input using MilWeb.MdispMessage. MIL does not have a similar function.

For C/C++, user interaction is not sent to the display automatically. Instead, you must forward user input from your MILweb client application to the display using MilWeb::MdispMessage. For more information, see the Making a presented display interactive subsection of the Creating a MILweb client application with C/C++ section later in this chapter.

Note that while a display can be shown simultaneously in many instances of your MILweb client, only one instance can have interactive control at a time.

Hooking to display events

You can hook a function to mouse or key press events in both your MILweb client and MILweb server applications (using MilWeb.MdispHookFunction and MdispHookFunction() respectively).

For your MILweb client, the function is hooked locally; the function is only called when the specified event is generated in the same instance of your MILweb client, and MilWeb.MdispGetHookInfo returns results (such as the mouse position) relative to this instance.

For your MILweb server, the function is hooked to whichever instance of the MILweb client has interactive control of the display; the function is only called when the specified event is generated on the computer with interactive control, and MdispGetHookInfo() returns results (such as the mouse position) about that instance.

For example, there might be 2 instances of your MILweb client (named client A and client B) running on 2 different computers, both connected to the same MILweb server and showing the same MILweb display. In this case, both clients have hooked a function to the MilWeb.M_MOUSE_LEFT_BUTTON_DOWN event and the MILweb server has hooked a function to the M_MOUSE_LEFT_BUTTON_DOWN event. Client A has interactive control of the display.

When the user of client A clicks on the display with the left mouse button, both client A and the MILweb server application call the functions that they have hooked to the event. MilWeb.MdispGetHookInfo and MdispGetHookInfo() return results about client A.

When the user of client B clicks on the display with the left mouse button, only client B calls the function that it has hooked to the event. MilWeb.MdispGetHookInfo returns results about client B.

MILweb messages

You can exchange any type of data between the MILweb client and MILweb server using message-passing through MIL message mailboxes.

Message mailboxes are allocated in your MILweb server application and accessed remotely by your MILweb client application. Your MILweb client can only access a message mailbox while connected to the MILweb server in which the message mailbox was allocated.

Sending messages from your MILweb server application

The following is a basic methodology to send a message from your MILweb server application to your MILweb client application:

  1. In your MILweb server application, allocate a message mailbox using MobjAlloc() with M_MESSAGE_MAILBOX and M_OVERWRITE.

    It is recommended to allocate message mailboxes for sending messages to MILweb clients with M_OVERWRITE. However, this is not a requirement. For more information, see the Message mailbox operation modes subsection of the Message mailboxes section of Chapter 48: Distributed MIL.

  2. In your MILweb server application, set the message mailbox to be published for access by MILweb clients using MobjControl() with M_WEB_PUBLISH and M_READ_ONLY.

    It is recommended to set message mailboxes for sending messages to MILweb clients to be M_READ_ONLY. However, this is not a requirement.

  3. In your MILweb server application, assign a name to the message mailbox using MobjControl() with M_OBJECT_NAME.

  4. In your MILweb client application, retrieve the MIL identifier of the message mailbox using MilWeb.MappInquireConnection and the name you assigned to the message mailbox.

  5. In your MILweb client application, hook a function to new messages being added to the message mailbox using MilWeb.MobjHookFunction with MilWeb.M_UPDATE_WEB.

  6. In your MILweb server application, write a message and add it to the message mailbox using MobjMessageWrite().

  7. In your MILweb client application, in the hook-handler function, read the contents of the message using MilWeb.MobjMessageRead.

    Messages are always transmitted as an array of type MIL_UINT8. For JavaScript, if the message contains text, you can convert the data to a string using the utility function MilWeb.convertUTF8ToString, which takes the message data as a parameter and returns it as a string. In rare cases where you send a message using UTF-16 encoding, use MilWeb.convertUTF16ToString instead.

Sending messages from your MILweb client application

The following is a basic methodology to send a message from your MILweb client application to your MILweb server application:

  1. In your MILweb server application, allocate a message mailbox using MobjAlloc() with M_MESSAGE_MAILBOX and M_QUEUE.

    It is recommended to allocate message mailboxes for receiving messages from MILweb clients with M_QUEUE. However, this is not a requirement. For more information, see the Message mailbox operation modes subsection of the Message mailboxes section of Chapter 48: Distributed MIL.

  2. In your MILweb server application, set the message mailbox to be published for access by MILweb clients using MobjControl() with M_WEB_PUBLISH and M_READ_WRITE.

  3. In your MILweb server application, assign a name to the message mailbox using MobjControl() with M_OBJECT_NAME.

  4. In your MILweb server application, hook a function to messages being added to the message mailbox using MobjHookFunction() with M_MESSAGE_RECEIVED.

  5. In your MILweb client application, retrieve the MIL identifier of the message mailbox using MilWeb.MappInquireConnection and the name you assigned to the message mailbox.

  6. In your MILweb client application, write a message and add it to the message mailbox using MilWeb.MobjMessageWrite.

  7. In your MILweb server application, in the hook-handler function, read the contents of the message using MobjMessageRead().