Clarification on api/apiUI

[stuckless]

From the sagetv javadoc, it says,

By default, all method calls made using the api call that need a user interface context will use the local user interface context.

From that, I can assume that if api() is used, then at any time it needs a UI context, it will default to SAGETV_PROCESS_LOCAL_UI.

But, if apiUI is called, with null, will it also default to SAGETV_PROCESS_LOCAL_UI? ie, will the following 3 statements yield the same results.

apiUI("SAGETV_PROCESS_LOCAL_UI", Cmd, Args)
apiUI(null, Cmd, Args)
api(Cmd, Args)

Also, does SageTV ignore the context for API calls that do not require a Context. ie, if I have a valid SageTV context, is it always safe to pass the UI context.

[GKusnick]

My experience is that calling apiUI() with a null context means no UI context, not the local UI context. So this way of calling it is useful only for methods that deal with global database and configuration data, and not for any UI-related API methods (i.e. those that change client settings, control media playback, etc).

Passing a context in to a method that doesn't require it does no harm; the method still operates on the shared global data regardless of which context you pass in.

The thing to remember is that when running in service mode, the service process has no local UI context. So in that case you must always pass in a valid context to do anything UI-related.

The rule I use in my API wrappers is to always call apiUI() instead of api(), and always pass in an explicit context if available, instead of relying on any defaulting behavior.

[stuckless]

Originally Posted by GKusnick

My experience is that calling apiUI() with a null context means no UI context, not the local UI context. So this way of calling it is useful only for methods that deal with global database and configuration data, and not for any UI-related API methods (i.e. those that change client settings, control media playback, etc).

Passing a context in to a method that doesn't require it does no harm; the method still operates on the shared global data regardless of which context you pass in.

The thing to remember is that when running in service mode, the service process has no local UI context. So in that case you must always pass in a valid context to do anything UI-related.

The rule I use in my API wrappers is to always call apiUI() instead of api(), and always pass in an explicit context if available, instead of relying on any defaulting behavior.

Thanks Greg. I suspected the same, but I just wanted make sure. I started thinking about this because I was looking at some code in the nielm webserver and I noticed that nielm was forcefully setting the UI context to the local context when no context was being passed.