MobileConnect is a communications infrastructure which runs on any OS2.0 Newton which allows it to connect to a LlamaShare server to serve and retreive information. The goal of MobileConnect is to make connecting to a LlamaShare server (LlamaServer) as simple as dropping in a file or two into your project and hooking up some callbacks to the application's user interface. Any application can now take advantage of the services provided by a LlamaServer without complicated endpoint and network programming by the application developer.
MobileConnect is not just a stand-alone server application, but can also be incorporated into any application, just by including the layout and several proto files. The API is well defined, and works with or without an application-supplied user interface. In fact, the NewtConnect server is just an application that provides a simple user interface and doesn't make use of any of the client-side routines.
NOTE: MobileConnect used to be called NewtConnect (in fact, that is what the server application used in most demos is still called). Any reference to NewtConnect can be interpreted as MobileConnect.
The MobileConnect infrastructure consists of 4 files (3 proto's and one layout):
|
In your main layout's viewSetupFormScript, add the following lines: |
// Create the FSM
fFSM := GetLayout("LlamaFSM"):Instantiate();
fFSM:MyInit();
// Provide parent inheritance for the FSM.
fFSM._parent := self;
|
|
This will create a slot in your top-level application frame called fFSM (or whatever you want to call it) which contains the finite state machine that deals with all the communications mumbo-jumbo. Your application need not be concerned with its internals. |
|
To connect to the server, you can either do it programatically, or let the user click a button and connect from a buttonClickScript. Either way, just call ConnectToServer() like this: |
// buttonClickScript
func ()
begin
fFSM:ConnectToServer(nil);
end
|
|
To disconnect, just use DisconnectFromServer() (again, either directly or in a callback). These routines are safe to call at any time. That is, they only are effective when in the correct state, and return harmlessly when not. After calling :ConnectToServer(), your application is can now serve information when a LlamaServer asks it to. That's it! |
If you want your app to be a server, you can ignore this section. However, if you want to be able to send and receive information to and from Global Soups from within your app, this section is for you!
There are currently three routines which your application can call to send/receive information:
I'll describe each of these routines indiviudally below, but each of the three takes one parameter, called a "clientSpec," which I will describe first because it is relevant to all of them.
A clientSpec is a frame with at least the following three slots:
|
|
|
Here is an example of a clientSpec for sending frames to the Global Soup:
fFSM:SendFramesToGlobalSoup ( { soupName: "Notes",
frames: [ {a: 34, b: "foo"}, {c:"bar"} ]
onCompletion:
func () begin
print ("we got some frames");
print (frames);
end } );
When this function succeeds, the onCompletion routine will be called and will print the text "we got some frames" and then print out the frames array to the inspector.
This routine reads all the frames from the GlobalSoup specified in the soupName slot of the clientSpec and stores it in the frames array.
This routine reads all the frames from the GlobalSoup specified in the soupName slot of the clientSpec and stores it in the frames array. In addition, it then clears the Global Soup in one atomic action. This is useful if you want to make sure that you have read an entire soup and guarantee that no new frames slip in between the time you read them and the time you clear the soup.
This routine takes the array of frames specified in the frames slot of the clientSpec and sends it to the Global Soup specified in the soupName slot.
For most cases, you can just pass "nil" as the parameter to ConnectToServer(), but if you want to be notified when the connection has been made to the server, you can pass a frame with an onCompletion routine (as above) which will be called after all the connection handshaking has finished.
Since the internal state machine can only handle one transaction at a time, if the machine is busy with one transaction, any subsequent client calls are ignored until the machine returns to the "ready" state. This can be useful for polling, as you can setup your app to poll every N seconds and not have to worry about whether or not the machine is busy with the previous request. If it is, it will just ignore the latest call and your app can try again the next time the timer goes off.
Because of how the internal FSM works, you can only execute an action when transitioning between states (on the arc, if you think about it as a graphical diagram). As a result, the onCompletion routine, which is called from the action, actually executes just before you are back in the "ready" state.
The main consequence of this is that you cannot, from an onCompletion routine, do anything that makes another client call. The reason for this is that you are not yet in the "ready" state, so the client call will be ignored. If you really need to do this, you will have to hack something that returns control to the main event loop (which finishes the state transition) and then makes the appropriate client call.
Talk to Jason Ellis if you have questions about how to do this (jellis@cc).