---------------------------------------------------
    vWall SDK 
---------------------------------------------------

This group of modules provides basic interfaces to SKM functionality: 

 SDK:
    - client authorization 

    - access to configuration of system objects

    - acess to credential info: user roles, user credentials, etc

    - gate to control vMUX daemon and Display Servers

 vMUX daemon:
    - daemon to manipulate single monitors and monitor walls

 Web services:

    - provide HTTP access to SDK functionality


---------------------------------------------------
Directory content:
---------------------------------------------------

bin - compiled JARs:
    encryptor.jar   - Encryptor class. Used to encrypt password
    sdk.jar         - SDK classes
    Services.aar    - Web services archive
    vmuxd.jar       - vMUX & vWall daemon

doc - all modules Java API documentation

etc - 
    virtual_services    - SDK configuration file

src - sources
    encryptor   - Encryptor class
    sdk         - SDK classes
    vmuxclient  - test SDK client application
    vmuxd       - vmux daemon classes
    websvc      - web services
        src     - generated sources, implementation is in *skeleton* classes
        wsdl    - WSDL file - services inerfaces definition

---------------------------------------------------
    To install SDK Web services into Axis:
---------------------------------------------------

Put  bin/encryptor.jar,
     bin/sdk.jar 
     lib/postgresql-8.2-505.jdbc3.jar

into webapps/axis2/WEB-INF/lib

Put bin/Services.aar    into    webapps/axis2/WEB-INF/services

Put virtual_services to /opt/sarch/etc
Update virtual_services to correct JDBC connection string, Postgres login & password, SDK log file path & log level.

    virtual_services params:
jdbc.drivers=org.postgresql.Driver - class name with JDBC implementation. org.postgresql.Driver is class from postgresql-8.2-505.jdbc3.jar
jdbc.url=jdbc:postgresql://127.0.0.1/postgres - connection string. "127.0.0.1" - DB host, "postgres" - DB name
jdbc.username=postgres  - DB user name
jdbc.password=123456    - DB user pass
VMUXDAEMON_IP = 127.0.0.1   - host IP addres where to connect vMUX daemon
VMUXDAEMON_PORT= 10001      - port to vMUX daemon listen to externaml connections
VMUXD_USERNAME=sdkuser      - vmuxdaemon credentials to open own SDK session.
VMUXD_USERPASS=74505E606519B10797C3D5718204F194B1343B - encrypted password to let vmuxd open own SDK session.
VMUXD_USERPASS_ENC=O930XAPGH5   - encryption string used to encrypt vmuxd password
LOG_FILE=d:/nextcam/vwall/vsdk.log  - path to log file
LOG_LEVEL=ALL   - log level. Other values: WARN, INFO, SEVERE


Load URL http://<host>:8080/axis2 and sure, Session_svc, Config_svc, Cred_svc and Wall_svc are in the list 
of installed services.

Use TIBCO or other application to send SOAP request to a Web service.


---------------------------------------------------
    Start vMUX daemon:
---------------------------------------------------
cd bin && ./vmuxd

---------------------------------------------------
    Modules' functions
---------------------------------------------------
    Session module:

open_session
close_session
is_valid
whose_sid
set_role
get_session_attributes
set_session_attributes

    Config module:

read_conf
save_conf

    Credential module:

get_resources
get_credentials
is_allowed
get_role_list
get_user_roles

    Wall module:

get_monitor_list
get_monitor_state
is_mon_changed
split_monitor
assign_stream
control_cells
get_walls
save_wall
save_layout
read_layout
get_layout_list
set_touring
lock (DEPRECATED)
unlock (DEPRECATED)
get_audio_devices (DEPRECATED)
get_screenshot (DEPRECATED)
get_audio_devices (DEPRECATED)
assign_audio (DEPRECATED)

---------------------------------------------------
    How to use SDK via WEB Services:
---------------------------------------------------

NOTE(!!!): Due to recent changes in authorization policy, SDK sessions are replaced by PHP sessions, so 'open_session' call
is no more required. Only two things should be done to start working with vMX Web Services:
  I. Set UID session attribute using 'set_session_attribute' call where 'name' parameter should be 'UID' and value should contain user ID
  II. Set current user's role with 'set_role' call

Direct SOAP requests ( ex. from TIBCO GUI ).

1. First step is Authorization - obtaining Session ID. Session ID is required for any other SDK call.

---------------------------------------------------
To obtain session ID use next SOAP request:

<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <SOAP-ENV:Body>
        <jsx1:name_pass xmlns:jsx1="websvc.videonext.com">
            <name>admin</name>
            <password>64223F647F701228175C5B4F41222D1F51516B66</password>
            <passEncryptionKey>aaa</passEncryptionKey>
        </jsx1:name_pass>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

where 'admin' is login user name,
<password> - contain encrypted password. To encrypt password use Encryptor.JAR. For ex: 

    java -jar encryptor.jar gendigest topse

will print like
DIGEST:354B435A111577967641580691C68713F427410
USED KEY:P09L61YTTF

<passEncryptionKey> - is encryption key used to encrypt password


In response Session service may send 'Access denied' response:

<?xml version='1.0' encoding='UTF-8'?>
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
        <soapenv:Body>
            <ns1:sid_out xmlns:ns1="websvc.videonext.com">
                <ns1:err_msg>Access denied for user 'admin'</ns1:err_msg>
            </ns1:sid_out>
    </soapenv:Body>
</soapenv:Envelope>


or successful message:

<?xml version='1.0' encoding='UTF-8'?>
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
        <soapenv:Body>
            <ns1:sid_out xmlns:ns1="websvc.videonext.com">
                <ns1:result>64223F647F701228175C5B4F41222D1F51516B66</ns1:result>
                <ns1:err_msg></ns1:err_msg>
            </ns1:sid_out>
    </soapenv:Body>
</soapenv:Envelope>

on successful login <ns1:result> will contain new Session ID value.

Java code for same result:

  import com.videonext.VSDK.*;
  import com.videonext.Encryptor;
...
  I_SessionManager smgr = I_SDK_impl.get_instance().get_Session_Mgr();

  String enkey = Encryptor.get_encryptionKey("");
  String dig = Encryptor.get_digest("topse", enkey);
  I_Session sobj = smgr.openSession ("admin", dig, enkey);


2. Selecting ROLE. 
---------------------------------------------------
    You need to select your working role because current role value associated with session ID 
    and used by credential service to resolve available user resources.
    List of avalable user's roles obtained by calling Credential service's "get_user_roles" method.

SOAP request:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <SOAP-ENV:Body>
        <m:sid_in xmlns:m="websvc.videonext.com">64223F647F701228175C5B4F41222D1F51516B66</m:sid_in>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

here  <m:sid_in> contains session ID, obtained after sucessful login


......
......
......

N. Controlling vMUX daemon, working with Monitors
---------------------------------------------------

New type of resource is Monitor, coded in DB as 'V'. Monitor corresponds to one display connected to Display Server.
It has Vres, Hres (resolution) properties and may be divided to cells. Video streams may be assigned to cells and playback control.

a) get_monitor_list

To get available monitors call Wall_svc#get_monitor_list

send SOAP request with SID and succesfull response will be somtheng like

<?xml version='1.0' encoding='UTF-8'?>
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
        <soapenv:Body>
            <ns1:obj_info_arr xmlns:ns1="websvc.videonext.com">
                <obj_info>
                    <ns1:objid>107</ns1:objid>
                    <name>monitor</name>
                    <desc>1024x768</desc>
                </obj_info>
            </ns1:obj_info_arr>
        </soapenv:Body>
    </soapenv:Envelope>

where 
107 - is OBJID of monitor object 
<name></name> contains short name for monitor
<desc>1024x768</desc> - description



b) get_monitor_state. 
---------------------------------------------------
    
This method returns monitor cells and change state number values.

In request SID and monitor ID are needed:

<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<SOAP-ENV:Body><jsx1:sid_objid xmlns:jsx1="websvc.videonext.com"><jsx1:sid_in>0662d1f391d7c6761203b2951d39</jsx1:sid_in><jsx1:objid>107</jsx1:objid></jsx1:sid_objid></SOAP-ENV:Body>
</SOAP-ENV:Envelope>

In response:

<?xml version='1.0' encoding='UTF-8'?><soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><soapenv:Body>
    <ns1:mon_state_out xmlns:ns1="websvc.videonext.com">
        <ns1:monitor_info id="107" hres="1024" vres="768" cellscount="2" statenum="2">
            <ns1:cell id="Cell 0.0" x="0" y="0" w="511" h="767" streamurl="rtsp://192.168.0.34/mpeg4/media.amp" streamstate="Stop" /><ns1:cell id="Cell 0.1" x="512" y="0" w="511" h="767" streamurl="rtsp://192.168.0.34/mpeg4/media.amp" streamstate="Play" />
        </ns1:monitor_info>
    </ns1:mon_state_out>
    </soapenv:Body></soapenv:Envelope>

where 
monitor_info contain: 
    id="107"    -  OBJID of monitor,
    hres="1024" - horizontal resolution
    vres="768"  - vertical resolution
    cellscount="2" - number of defined cells
    statenum="2"    - change number - autoincremented on every outer sucessful change of monitor state
cells info:  
    id="Cell 0.0" - cell ID. May need later to asssing streams to this cell
    x="0" y="0" w="511" h="767" - left-top point of cell and width, heght values in pixels
    streamurl="rtsp://192.168.0.34/mpeg4/media.amp" - URL of video stream assigned to tis cell
    streamstate="Stop" - playback state.



c) is_mon_changed.
---------------------------------------------------

Call  this method to check whether monitor state changed by somebody.

In call you must provide SID, Monitor ID and change state number compare with

It returns True when daemon's state of  the monitor differs from provided one.

SOAP request:

<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<SOAP-ENV:Body><jsx1:sid_objid_int xmlns:jsx1="websvc.videonext.com"><jsx1:sid_in>0662d1f391d7c6761203b2951d39</jsx1:sid_in><jsx1:objid>107</jsx1:objid><jsx1:state_num>0</jsx1:state_num></jsx1:sid_objid_int></SOAP-ENV:Body>
</SOAP-ENV:Envelope>


SOAP response:

<?xml version='1.0' encoding='UTF-8'?><soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><soapenv:Body>
    <ns1:bool_out xmlns:ns1="websvc.videonext.com">
        <result>true</result>
    </ns1:bool_out>
</soapenv:Body></soapenv:Envelope>


d) Splitting to cells
---------------------------------------------------

SOAP request:

<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<SOAP-ENV:Body><jsx1:split_info xmlns:jsx1="websvc.videonext.com">

<jsx1:sid_in>0662d1f391d7c6761203b2951d39</jsx1:sid_in>

<jsx1:objid>107</jsx1:objid>

<cellmatrix rows="1" cols="2"/>

<jsx1:cell id="cell1" x="0" y="0" w="100" h="100" streamurl="rtsp://192.168.0.34/mpeg4/media.amp" streamstate="Play"/>

</jsx1:split_info></SOAP-ENV:Body>
</SOAP-ENV:Envelope>


where

sid_in - session ID
objid - Monitor ID
cellmatrix - parameter to define table of cells (rows * cols)
cell - one or more tags define cells position and streams. When all cells has x, y, w, h attributes cellmatrix is ignored.
    daemon try to split to defined cells and dimentions.
    When one or more (all) cells doesnt define x, y, w, h attributes then cellmatrix used to automatcally split monitor

Sucessful split response:

<?xml version='1.0' encoding='UTF-8'?><soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><soapenv:Body><ns1:bool_out xmlns:ns1="websvc.videonext.com">

    <result>true</result>

</ns1:bool_out></soapenv:Body></soapenv:Envelope>

On error you'll get
    <result>false</result>
and 
    <err_msg> tag with exception text



e) Assign streams
---------------------------------------------------

SOAP request:

<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<SOAP-ENV:Body><jsx1:assign_info xmlns:jsx1="websvc.videonext.com">

    <jsx1:sid_in>0662d1f391d7c6761203b2951d39</jsx1:sid_in>

    <jsx1:objid>107</jsx1:objid>

    <cellurls id="Cell 0.1" streamurl="rtsp://192.168.0.34/mpeg4/media.amp" streamstate="Play"/>

</jsx1:assign_info></SOAP-ENV:Body>
</SOAP-ENV:Envelope>

where

sid_in - session ID
objid - Monitor ID
cell - one or more tags defining cells' streams. 
    

Sucessful assign response:

<?xml version='1.0' encoding='UTF-8'?><soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><soapenv:Body><ns1:bool_out xmlns:ns1="websvc.videonext.com">

    <result>true</result>

</ns1:bool_out></soapenv:Body></soapenv:Envelope>


====================================================

You can get more detailed info and examples from the document:
    http://svn.dev.videonext.net/svn/documents/Releases/2.6/API%202.6.2.doc
    