Library: Remote APIs for SageTV

[shadeblue.com]

Originally Posted by stuckless

I have put some thought into how to transparently handle the "context" problem. Initially, I didn't need to use the context, so it got put on the back burner, but I'll spend some time and try to come up with something.

My initial thoughts are along these lines....
1. for each generated method, generate a second method that also can accept a context parameter, so WidgetAPI would include a method ExecuteWIdgetChain(widget) and ExecuteWidgetChain(widget, context).

2. add a theadlocal variable to generated class, so that you can set the context before executing the method. So, when you call ExecuteWidgetChain, you'd have to set the context first, so something like this...

sagex.api.WidgetAPI.SetContext(context);
sagex.api.WidgetAPI.ExecuteWidgetChain(widget);
sagex.api.WidgetAPI.SetContext(null);

The issue I see with the ThreadLocal approach is that I don't know how Sage handles it's UI code on the server. ie, if you were to run this code within sage, does sage execute each ui in it's own thread, or do all threads share the same thread....

3. Create a static list of "context" enabled fields and modify the generator to ONLY create context aware methods for methods that can accept a context...

Any thoughts?

Hi Sean,

Ok, I did not realize that a UI context was needed for each of these calls. I am very new to writing against Sage, so I am learning as I go.

As far as your suggestions, I would be totally fine with any of the proposed implementations. I think that #1 would ensure that the programmer consciously specifies the correct context, opposed to #2 where a programmer could get a little careless and lose track of which context is currently set. The wrapper option would be nice, but if that is not a design goal for your API then .....

By the way, thank you for your API. The remoting capability is one thing I was looking for. Soon, I will be looking into playing with the REST based client implementation.

Thanks again,
shadeBlue

[stuckless]

By the way, thank you for your API. The remoting capability is one thing I was looking for. Soon, I will be looking into playing with the REST based client implementation.

Thanks... and just so you know... the REST api already support the notion of a UI context. Check the documentation for more information about how to pass the UI context when using the Rest APIs.

[stuckless]

I just upated the Remote APIs to include a way to set the UI context for a call. I decided to go with the ThreadLocal method until I decide there is a better way, or until someone else points out it's critical flaw

The core API, sagex.SageAPI now contains a deprecated method, setUIContext(String context). The method is deprecated because I haven't tested how it will function if the code is embedded in a SageTV JVM. The method is perfectly safe to use for any remote calls as long your are running in a single thread or your code is thread safe. So, for the most part, you should have no issues setting the context for remote applications.

To set the context, you can use a convenience method that is generated for each API (ie, WidgetAPI, Global, MediaFile, etc).

Here is an example that gets all the contexts and then prints out the stv file being used for each context.

		String uiContexts[] = Global.GetUIContextNames();
		for (String ui : uiContexts) {
			System.out.println("Context: " + ui);
			WidgetAPI.setUIContext(ui);
			System.out.printf("Current STV File: %s\n", WidgetAPI.GetCurrentSTVFile());
		}

Keep in mind that in any code where you need to call multiple SageAPIs that require a UI Context, then you ONLY need to set the context once. You can set it as many times as you want, but only need to set it once.

you can get the latest release from the downloads section.

[GKusnick]

Originally Posted by shadeblue.com

Ok, I did not realize that a UI context was needed for each of these calls.

The server process can host multiple remote clients, each with its own instance of the UI and (potentially) a different STV loaded in each one. So the general rule of thumb is that anything that interacts with the UI, such as manipulating widgets or playing media, requires a UI context in order to know which UI instance to operate on.

API calls that interact only with the database, recording engine, or global configuration can generally get away without specifying a UI context.

[shadeblue.com]

Originally Posted by GKusnick

The server process can host multiple remote clients, each with its own instance of the UI and (potentially) a different STV loaded in each one. So the general rule of thumb is that anything that interacts with the UI, such as manipulating widgets or playing media, requires a UI context in order to know which UI instance to operate on.

API calls that interact only with the database, recording engine, or global configuration can generally get away without specifying a UI context.

That makes sense and I had seen the use of context in nielms getinfostatus plugin and in the webserver plugin, I just has not yet seen an example of code that directly controlled the user interface via the 'WidgetAPI'. I did download Sean's updated API library last night and did get some basic code working that was able to launch a menu. Yeah!

One question about the widget symbols. If a STVi plugin is deployed and it adds Widgets to other persons instance of Sage, does it generate new Widget symbols or does it maintain the consistent assigned Widget symbol? I guess what I am gettting at is if I use 'GetWidgetSymbol' to find a specific menu item, can I rely on that lookup to work on everybody's instance of SageTV provided that the menu item exists or was imported via STVi?

Thank again for your help,
shadeBlue

[GKusnick]

Yes, that's the whole point of widget symbols: to be the globally unique handle by which you can address a widget in any instance of Sage. (However this does require the STV/STVI author to correctly configure their copy of Studio with a unique symbol prefix to avoid collisions with widgets created by other developers.)

[shadeblue.com]

Originally Posted by GKusnick

Yes, that's the whole point of widget symbols: to be the globally unique handle by which you can address a widget in any instance of Sage. (However this does require the STV/STVI author to correctly configure their copy of Studio with a unique symbol prefix to avoid collisions with widgets created by other developers.)

Awesome, I think I am going to take a stab at an alternative to nielms caller ID info popup, one that might work with the HD extender.

Thanks again,
shadeBlue

[shadeblue.com]

Hi Sean,

I have been using the latest version of your sagex.api with great success. However, I have run into one minor issue that maybe you could provide some insight on. I am using the REST based api on my current project and I am looking to submit a request like this:

http://sagetv:8080/sagex/rpcXml/Global/SageCommand/Channel%20Down%2CPage%20Down/context:SAGETV_PROCESS_LOCAL_UI


Where "Channel Down/Page Down" is the command parameter for the 'SageCommand' method.

I can't send the raw text version of the command parameter because of the "/" character in the string, I think this would be interpreted as part of the url resources in the REST processing. So I URL encoded the character as "%2C", but this does not seem to work either. So I guess my question is ... how do I encode special characters like this one for the REST server to interpret it correctly? Is there a REST encoding format?

Thank You,
shadeBlue

[shadeblue.com]

Hi Sean,

On another project I am using the sagex SageAPI java client. How do I set the address of the sage server I want to connect to?

The api is automatically connecting to a sage server, but not the one that I want it to....

SageAPI Provider is not set, will try to find the server...
Sage Provider Implementation: sagex.remote.SageAPIRemote; http://192.168.10.14:80/sagex/rpcJava


Thanks,
shadeBlue

[stuckless]

How do I set the address of the sage server I want to connect to?

At the start of your Application, you need to do the following....

sagex.SageAPI.setProvider(new SageAPIRemote(YOUR_SERVER_URL));

By Default if a URL is NOT set, then it will use UDP discovery to find a server to connect to.

I may look at adding a -DpreferredSageSage=URL to the API, so that you could pass the preferred server on java command line.

As for your Rest Issues... I will consider that a bug in my Rest API... and I'll try to have a fix sometime tonight or tomorrow.

The api allows for the arguments and context to be passed as reqular url parameters, but I forgot to allow the command to be passed as a url parameter...
ie., in the existing API

rpcXML/Command/Arg1/Arg1/context:CONTEXT

can also be passed as

rpcXML/Command?1=Arg1&2=Arg2&context=CONTEXT

what i need to do is also allow the command to be passed, such as

rpcXML?command=command&1=Arg1&2=Arg2&context=CONTEXT

for those really special cases where command and/or args contain a '/'

[shadeblue.com]

Originally Posted by stuckless

....
As for your Rest Issues... I will consider that a bug in my Rest API... and I'll try to have a fix sometime tonight or tomorrow.
....

Awesome! Thank You!,
shadeBlue

[stuckless]

6.4.8-3 now supports being able to pass the command as a url paramter,

Example

http://mediaserver:8080/sagex/rpcXml/Global?command=RunLibraryImportScan&1=false

Note the arguments are passed as sequential name value pairs. In the case above "false" is the "1"st argument.

[shadeblue.com]

Originally Posted by stuckless

6.4.8-3 now supports being able to pass the command as a url paramter,

Example

http://mediaserver:8080/sagex/rpcXml/Global?command=RunLibraryImportScan&1=false

Note the arguments are passed as sequential name value pairs. In the case above "false" is the "1"st argument.

Hi Sean, the update works great for the commands with a "/" character. However, I ran into one other command problem:
When trying to send the "SageCommand" with argument "Skip Fwd #2"

http://sagetv:8080/sagex/rpcXml/Global?command=SageCommand&1=Skip Fwd #2&context=SAGETV_PROCESS_LOCAL_UI

I think it does not like the pound "#" character. I tried URL encoding this character, but that did not work either. I did verify that via the Java API this command works fine, just not the REST API.

Sorry to keep pestering you with these minor issues :-)

Thanks, shadeBlue

[jreichen]

Originally Posted by stuckless

As for your Rest Issues... I will consider that a bug in my Rest API... and I'll try to have a fix sometime tonight or tomorrow.

The api allows for the arguments and context to be passed as reqular url parameters, but I forgot to allow the command to be passed as a url parameter...
ie., in the existing API

rpcXML/Command/Arg1/Arg1/context:CONTEXT

can also be passed as

rpcXML/Command?1=Arg1&2=Arg2&context=CONTEXT

what i need to do is also allow the command to be passed, such as

rpcXML?command=command&1=Arg1&2=Arg2&context=CONTEXT

for those really special cases where command and/or args contain a '/'

Either way you need to use Java's URLDecoder class to handle special characters.

[stuckless]

Either way you need to use Java's URLDecoder class to handle special characters.

The rpcHandler is a HttpServlet instance, and it uses, request.getParameter() which should perform the necessary URLDecoding for you.

I did do some quick tests this morning... enought to confirm that SageComannd works with "Pause" and "Play", but not with "Skip Fwd #2". I'll do testing tonight (i'm at work now ) to see if it's a result of the REST api.

[stuckless]

I think that your problem is that the parameter was not URL encoded correctly. "Skip Fwd #2" url encodes to Skip+Fwd+%232. When I passed that URL encoded parameter, my sage did process the Skip command correctly.

Here's an online tool for URL Encoding.

[shadeblue.com]

Originally Posted by stuckless

I think that your problem is that the parameter was not URL encoded correctly. "Skip Fwd #2" url encodes to Skip+Fwd+%232. When I passed that URL encoded parameter, my sage did process the Skip command correctly.

Here's an online tool for URL Encoding.

Hi Sean,

You are correct, I was being lazy on the URL encode. The spaces seem to work in the other commands when no url encoding is performed, but I guess if I url encode one character, I need to properly url encode the whole string. I have updated my code to properly url encode the whole string and it works great! Sorry for the false alarm :-)

Thank You!

[shadeblue.com]

Hi Sean,

I have posted a project to the community that is based on your remoting API:
SageTV Remote Control


Thanks for all your help!

Cheers,
shadeBlue.com

[jreichen]

Sean,

I've been working with the remote Java RPC API and ran into an issue. It looks like the payload on the request is being sent as part of the URL, and once that exceeds a certain length (a few kbytes) it fails. Here's the code to reproduce the problem. I added the "copyOfRange" function to reduce the size of the array for troubleshooting.

String[] titles = (String[]) sagex.SageAPI.call("GetAllTitles", null);
// change the size of the array to test the URL size limit
//titles = Arrays.copyOfRange(titles, 0, 100);
Object[] params = new Object[] {titles, true, null};
titles = (String[]) sagex.SageAPI.call("Sort", params);

for (String title : titles)
{
    System.out.println(title);
}

Jason

[stuckless]

I've been working with the remote Java RPC API and ran into an issue.

When I wrote the http code to send commands, i quickly used a simple url get method. I'll update the code so that it will now "post" the data instead of just building a url. doing http post is slightly more effort, which is why I used get to begin with... I'll try to get a fix out this weekend.