Barco Apollo User guide

•

Reference manual

APOLLO REL. 1.8 SOAP API

DOC-3338-2

DOC

DOCDOC

DOC-

-3338

33383338

3338-

-2, Current Version

2, Current Version2, Current Version

2, Current Version

Title: Apollo Release 1.8 SOAP API – Reference Manual

ID-no.: DOC-3338-2

Revision: 06

Date: Nov-2005

main issue update

Introduction

Functionality

Data Structures Add ViewerMouseEvent; VideoStatus; VideoViewPort; RGB;

RGBPreset

Exceptions

Infrastructure API

DesktopManagement API

DeviceManagement API Add getViewerMouseEvents

ViewerManagement API Add Video quality functions 10.21 – 10.37

Corr 9.5 getDeviceStatus: the type of the result must be a “list

of 32 bit values” instead of “Integer[]”.

9.6 getProjectorStatus: results “0”, “2” are missing.

9.10 activateProjectorLamp: the type of the parameter

aLamp must be a “16 bit value” instead of “Integer”.

9.11 getActiveProjectorLamp: the type of the return value

must be a “16 bit value” instead of “Integer”.

8.2, 8.3, 8.5 – 8.8, 8.10 – 8.19, 9.2 – 9.15, 10.4, 10.5: The

FaultString string, due to a typo, must be

“InnternalTimeout” (with doubled ‘n’) instead of

“InternalTimeout”.

9.2 – 9.15: The FaultCode string, due to a typo, must be

“Device unkown” (without ‘n’) instead of “Device

unknown”.

9.12, 9.13, 9.14: the type of the result must be a “list of 32

bit values” instead of “Integer[]”.

new: The corresponding chapters are new or completely revised.

corr.: Passages of the corresponding chapter were corrected; see modification bars.

add.: Passages of the corresponding chapter were added; see modification bars.

Document History

Document HistoryDocument History

Document History

A vertical bar indicates modifications, which result in a new version.

Trad

TradTrad

Trademarks

emarksemarks

emarks

Brand and product names mentioned in this manual may be trademarks, registered trademarks or copyrights of

their respective holders. All brand and product names mentioned in this manual serve as comments or examples

and are not to be understood as advertising for the products or their manufacturers.

-2005 by BARCO

2005 by BARCO2005 by BARCO

2005 by BARCO

Die Weitergabe sowie die Vervielfältigung aller Unterlagen, die von uns überlassen werden, deren Verwertung

und Mitteilung ihres Inhaltes an Dritte ist nicht gestattet, soweit dies nicht ausdrücklich zugestanden ist.

Urheberrechte, insbesondere auch solche an Software, werden nur insoweit übertragen, als es für die Erreichung

des speziellen Vertragszwecks erforderlich ist. Zuwiderhandlungen können zu Schadensersatz verpflichten. Alle

Rechte aus der Erteilung eines Patents oder der Eintragung eines Gebrauchsmusters verbleiben bei uns.

-2005 by BARCO

2005 by BARCO2005 by BARCO

2005 by BARCO

recorded, transmitted or stored in a retrieval system without the prior written consent of BARCO.

Guarantee and Compensation

Guarantee and CompensationGuarantee and Compensation

Guarantee and Compensation

BARCO provides a guarantee relating to perfect manufacturing as part of the legally stipulated terms of

guarantee. On receipt, the purchaser must immediately inspect all delivered goods for damage incurred during

transport, as well as for material and manufacturing faults. BARCO must be informed immediately in writing of

any complaints.

The period of guarantee begins on the date of transfer of risks, in the case of special systems and software on

the date of commissioning, at the latest 30 days after the transfer of risks. In the event of justified notice of

complaint, BARCO can repair the fault or provide a replacement at its own discretion within an appropriate

period. If this measure proves to be impossible or unsuccessful, the purchaser can demand a reduction in the

purchase price or cancellation of the contract (redhibition). All other claims, in particular those relating to

compensation for direct or indirect damage, and also damage attributed to the operation of software as well as

to other services provided by BARCO, being a component of the system or independent services, will be deemed

invalid provided the damage is not proven to be attributed to the absence of properties guaranteed in writing or

due to the intent or gross negligence on the part of BARCO.

If the purchaser or a third party carries out modifications or repairs on good delivered by BARCO, or if the goods

are handled incorrectly, in particular if the systems are commissioned or operated incorrectly or if, after the

transfer of risks, the goods are subject to influences not agreed upon in the contract, all guarantee claims of the

purchaser will be rendered invalid. Not included in the guarantee coverage are system failures, which are

attributed to programs or special electronic circuitry provided by the purchaser, e. g. interfaces. Normal wear as

well as normal maintenance are not subject to the guarantee provided by BARCO either.

The customer must comply with the environmental conditions as well as the servicing and maintenance

regulations specified in this manual.

Revision sheet

Revision sheetRevision sheet

Revision sheet

To:

• Barco Control Rooms GmbH

An der Rossweid 5, D-76229 Karlsruhe

Phone: +49-721-6201-0, Fax: +49-721-6201-298

E-mail:

docu.de.[email protected]m, Web: www.barcocontrolrooms.com

From:

Date:

Please correct the following points in this documentation (DOC-3338-2):

Page Wrong correct

Contents

ContentsContents

Contents

1 Introduction........................................................................................................................................ 1-1

1.1 How this manual is organized ....................................................................................................................1-1

1.2 Styles and Symbols .....................................................................................................................................1-2

2 Functionality.......................................................................................................................................2-1

2.1 Background ..................................................................................................................................................2-1

2.2 Basic Client Side Setup ................................................................................................................................2-1

3 Sample Application for Microsoft VisualStudio.net .......................................................................... 3-1

3.1 Client Side Setup..........................................................................................................................................3-1

3.2 Creating the Sample....................................................................................................................................3-1

3.2.1 Wizard Approach.................................................................................................................................3-2

3.2.2 Manual Approach................................................................................................................................3-2

4 Sample Application for Java ..............................................................................................................4-1

4.1 Client Side Setup..........................................................................................................................................4-1

4.2 Creation of Proxy Classes with JBuilder9....................................................................................................4-1

4.3 Creation of Proxy Classes with Eclipse 3.0.2 ..............................................................................................4-2

4.4 Creation of a Java Sample Application .......................................................................................................4-3

4.4.1 First ‘Hello world’ sample ..................................................................................................................4-3

5 Data Structures................................................................................................................................... 5-1

5.1 DesktopID.....................................................................................................................................................5-1

5.2 RegionID.......................................................................................................................................................5-1

5.3 LayoutID .......................................................................................................................................................5-1

5.4 WindowID ....................................................................................................................................................5-1

5.5 ShortcutID ....................................................................................................................................................5-2

5.6 ViewerID ......................................................................................................................................................5-2

5.7 SourceID .......................................................................................................................................................5-2

5.8 DeviceID .......................................................................................................................................................5-2

5.9 Geometry .....................................................................................................................................................5-2

5.10 IDC ..............................................................................................................................................................5-3

5.11 IDC2............................................................................................................................................................5-3

5.12 StatusBorder ..............................................................................................................................................5-4

5.13 ViewerDecoration......................................................................................................................................5-4

5.14 ViewerMouseEvent....................................................................................................................................5-4

5.15 VideoChannel.............................................................................................................................................5-5

5.16 VideoViewPort ...........................................................................................................................................5-5

5.17 VideoStatus ................................................................................................................................................5-5

5.18 RGB.............................................................................................................................................................5-6

5.19 RGBPreset ..................................................................................................................................................5-6

5.20 StreamingVideoChannel............................................................................................................................5-6

5.21 StreamingVideoBoardSettings ..................................................................................................................5-6

5.22 ScreenChannel ...........................................................................................................................................5-7

5.23 ScreenChannel2.........................................................................................................................................5-7

5.24 WebChannel...............................................................................................................................................5-7

5.25 SegmentID .................................................................................................................................................5-7

5.26 InputChannelID ..........................................................................................................................................5-7

6 Exceptions .......................................................................................................................................... 6-1

6.1 InternalError .................................................................................................................................................6-1

6.2 InternalTimeout ...........................................................................................................................................6-1

6.3 InvalidID .......................................................................................................................................................6-1

6.4 FunctionNotSupported.................................................................................................................................6-1

6.5 ServiceOffline...............................................................................................................................................6-1

7 Infrastructure API...............................................................................................................................7-1

7.1 logMessage..................................................................................................................................................7-1

7.2 logWarning ..................................................................................................................................................7-1

7.3 logError.........................................................................................................................................................7-1

7.4 getSystemStatus..........................................................................................................................................7-1

7.5 getKey2String ..............................................................................................................................................7-2

7.6 getVersion....................................................................................................................................................7-2

7.7 ResetAPI.......................................................................................................................................................7-2

8 DesktopManagement API..................................................................................................................8-1

8.1 enumerateDesktops ....................................................................................................................................8-1

8.2 enumerateRegions ......................................................................................................................................8-1

8.3 enumerateShortcuts....................................................................................................................................8-1

8.4 getDesktopGeometry ..................................................................................................................................8-2

8.5 enumerateWindows ....................................................................................................................................8-2

8.6 getWindowGeometry ..................................................................................................................................8-3

8.7 setWindowGeometry...................................................................................................................................8-3

8.8 closeWindow................................................................................................................................................8-4

8.9 activateWindow ..........................................................................................................................................8-4

8.10 getRegionGeometry ..................................................................................................................................8-4

8.11 enumerateLayouts ....................................................................................................................................8-4

8.12 getLayoutStack ..........................................................................................................................................8-5

8.13 activateLayout ...........................................................................................................................................8-5

8.14 deactivateLayout .......................................................................................................................................8-6

8.15 updateLayout.............................................................................................................................................8-6

8.16 saveAsLayout.............................................................................................................................................8-7

8.17 startApplication .........................................................................................................................................8-7

8.18 startShortcut ..............................................................................................................................................8-7

8.19 sendCommandLine....................................................................................................................................8-8

9 DeviceManagement API ....................................................................................................................9-1

9.1 enumerateDevices.......................................................................................................................................9-1

9.2 enumerateSegments...................................................................................................................................9-1

9.3 getSegmentGeometry.................................................................................................................................9-2

9.4 enumerateSegmentInputChannels .............................................................................................................9-2

9.5 getDeviceStatus...........................................................................................................................................9-3

9.6 getProjectorStatus .......................................................................................................................................9-3

9.7 switchProjectorLamp ...................................................................................................................................9-4

9.8 getProjectorActiveLampStatus ....................................................................................................................9-4

9.9 getProjectorInactiveLampStatus .................................................................................................................9-5

9.10 activateProjectorLamp ..............................................................................................................................9-5

9.11 getActiveProjectorLamp............................................................................................................................9-6

9.12 getProjectorRuntime .................................................................................................................................9-6

9.13 getProjectorActiveLampRuntime ..............................................................................................................9-6

9.14 getProjectorInactiveLampRuntime ...........................................................................................................9-7

9.15 sendCommandLine....................................................................................................................................9-7

10 ViewerManagement API................................................................................................................10-1

10.1 enumerateViewers................................................................................................................................. 10-1

10.2 enumerateSources ................................................................................................................................. 10-1

10.3 enumerateStreamingSources................................................................................................................. 10-2

10.4 connectSource ........................................................................................................................................ 10-2

10.5 disconnectSource.................................................................................................................................... 10-2

10.6 setStreamingSource ............................................................................................................................... 10-3

10.7 setIDCs .................................................................................................................................................... 10-3

10.8 setIDC2s .................................................................................................................................................. 10-3

10.9 getIDCs .................................................................................................................................................... 10-4

10.10 getIDC2s................................................................................................................................................ 10-4

10.11 setDecoration ....................................................................................................................................... 10-4

10.12 getDecoration....................................................................................................................................... 10-5

10.13 getMouseEvents ................................................................................................................................... 10-5

10.14 setVideoChannel................................................................................................................................... 10-5

10.15 getVideoChannel .................................................................................................................................. 10-5

10.16 setStreamingVideoChannel.................................................................................................................. 10-6

10.17 getStreamingVideoChannel ................................................................................................................. 10-6

10.18 setStreamingVideoBoardSettings ........................................................................................................ 10-6

10.19 getStreamingVideoBoardSettings........................................................................................................ 10-7

10.20 startVideoChannel ................................................................................................................................ 10-7

10.21 stopVideoChannel................................................................................................................................. 10-7

10.22 getVideoStatus ..................................................................................................................................... 10-8

10.23 setVideoBrightness............................................................................................................................... 10-8

10.24 getVideoBrightness .............................................................................................................................. 10-8

10.25 setVideoSharpness ............................................................................................................................... 10-9

10.26 getVideoSharpness............................................................................................................................... 10-9

10.27 setVideoContrast .................................................................................................................................. 10-9

10.28 getVideoContrast ................................................................................................................................ 10-10

10.29 setVideoSaturation ............................................................................................................................. 10-10

10.30 getVideoSaturation............................................................................................................................. 10-10

10.31 setRGBSaturation................................................................................................................................ 10-11

10.32 getRGBVideoSaturation...................................................................................................................... 10-11

10.33 enumerateRGBPresets ....................................................................................................................... 10-11

10.34 setActiveRGBPreset............................................................................................................................ 10-11

10.35 getActiveRGBPreset ........................................................................................................................... 10-12

10.36 getRGBAutoSignalDetectionMode ..................................................................................................... 10-12

10.37 setVideoViewPort ............................................................................................................................... 10-13

10.38 getVideoViewPort............................................................................................................................... 10-13

10.39 setScreenChannel............................................................................................................................... 10-13

10.40 getScreenChannel .............................................................................................................................. 10-14

10.41 setScreenChannel2............................................................................................................................. 10-14

10.42 getScreenChannel2 ............................................................................................................................ 10-14

10.43 takeControlOfScreenChannel ............................................................................................................. 10-15

10.44 releaseControlFromScreenChannel.................................................................................................... 10-15

10.45 setWebChannel................................................................................................................................... 10-15

10.46 getWebChannel .................................................................................................................................. 10-16

10.47 sendCommandLine............................................................................................................................. 10-16

11 Appendix......................................................................................................................................11-16

11.1 Verbose information............................................................................................................................. 11-16

1. Introduction

BARCO – Apollo 1.8 SOAP API – DOC-3338-2 – Reference manual – Revision 06 – Nov-2005

___________________________________________

1-1

1 Introduction

This chapter explains the structure of the manual itself and the used typographic styles and symbols.

1.1 How this manual is organized

This manual describes the functionality of the Apollo SOAP Interface. It is divided into six chapters:

• Introduction

explains the structure of the manual itself and the used typographic styles and symbols.

• Functionality

describes how the SOAP interface can be used.

• Sample Application for VisualStudio.Net

explains, how to setup for and create a client application in Microsoft VisualStudio.Net

• Sample Application for Java

explains, how to setup for and create a client application in Java

• Data Structures

lists all complex types and gives an overview about their usage.

• Exceptions

lists all exceptions, which are thrown by the functions.

• Infrastructure API

lists all functions and gives a tabular overview about their usage.

• DesktopManagement API

lists all functions and gives a tabular overview about their usage.

• DeviceManagement API

lists all functions and gives a tabular overview about their usage.

• ViewerManagement API

lists all functions and gives a tabular overview about their usage.

• Appendix A –

Chapters, pages, figures and tables are numbered separately. Chapters are indicated by a »point syntax«, e. g.

4.2.3, pages by a »dash syntax«, e. g. 2-1, as figures and tables are, e. g. figure 5-4..

1. Introduction

BARCO – Apollo 1.8 SOAP API – DOC-3338-2 – Reference manual – Revision 06 – Nov-2005

___________________________________________

1-2

1.2 Styles and Symbols

The typographic styles and the symbols used in this document have the following meaning:

Bold Labels, menus and buttons are printed in Bold font.

Condensed

Links to both other chapters of this manual and to sites in the Internet are printed

condensed. In the on-line version of this manual all hyperlinks appear teal.

Courier Names of files and parts from programs are printed in the Courier font.

Courier bold Inputs you are supposed to do from the keyboard are printed in Courier bold font.



Within a piece of programming code this arrow marks a line, that must be made up in two

lines, though meant to be one line.

If you do not heed instructions indicated by this symbol there is a risk of damage to the

equipment!

If you do not heed instructions indicated by this symbol there is a risk of electrical shock and

danger to personal health!

If you do not heed instructions indicated by this symbol there is a risk of damage to parts,

which are sensitive towared electrostatic charge!

If you do not heed instructions indicated by this symbol there is a risk to get harmed by sharp

objects!

If you do not heed instructions indicated by this symbol there is a risk that parts may

explode!

If you do not heed instructions indicated by this symbol there is a risk that hot parts impact

persons or objects!

The sheet icon indicates additional notes.

Next to this icon you find further information.

This arrow marks tips.

Next to this icon you find important notes.

2. Functionality

BARCO – Apollo 1.8 SOAP API – DOC-3338-2 – Reference manual – Revision 06 – Nov-2005

___________________________________________

2-1

2 Functionality

The SOAP API exposes most of the Apollo functionalities to third-party application programs, thus allowing for

tight integration of Apollo with higher-level control logic. The SOAP API is a Remote Procedure Call (RPC) type of

API using plain function calls from a client to a server. SOAP follows the HTTP request/response model that

means the service cannot send updates event driven. Structured data types are used to keep the API clean,

stable and easy to use.

2.1 Background

The SOAP API is a bridge between an external application and Apollo’s internal communication system. It consists

of a number of API modules, which will be hosted by an Internet Information Server (IIS) executing somewhere

in the configuration. Typically the IIS will be configured to run on the wall controller (EOS or Argus). It is not

foreseen to use an existing IIS for this purpose or host other, not Apollo related applications on the IIS.

The IIS will expose a virtual directory named ApolloAPI. In that directory it provides the Web Service Descriptions

(WSDL documents) of all APIs. APIs are structured according to Apollo’s subsystems, namely Desktop

Management, Device Management and Viewer Management. There is one more API addressing system wide,

infrastructural functionalities, called Infrastructure.

Using the WSDL documents, which can also be obtained upfront without having a functional Apollo system, a

customer can create a SOAP client application. This is usually done with the help of a SOAP toolkit. Toolkits are

typically dedicated to a certain programming language; however, SOAP interfaces can be used from different

programming languages. Most notably, all Microsoft .net programming languages are SOAP enabled.

There are different SOAP toolkits on the market, commercial ones and free ones. Barco will not be able to test its

APIs against all of these, but will instead document, which toolkits have been verified. In order to provide you

with the best possible support, we recommend using one of the specified toolkits. Because of its widespread

acceptance in the market, Microsoft .net is considered the standard case for client-side applications.

The samples have been provided for multiple programming environments and should be used as examples

exercising the SOAP API.

2.2 Basic Client Side Setup

The service side setup of the API is part of an Apollo Rel. 1.5 (or greater) setup. Please refer to the Apollo User

Manual about how to setup the service.

In order to verify the availability of the API follow these steps on one of the client systems (or the intended

development system):

• On a command prompt type:

ping ApolloAPIServer

and expect a response like:

Pinging ApolloApiServer [150.158.72.139] with 32 bytes of data:

Reply from 150.158.72.139: bytes=32 time<10ms TTL=128

This verifies, that the DNS name of the server is known. It either has been added to the local DNS system, or

–if this was not possible- had to be added to all the clients’ hosts file. If you can’t ping the server you need to

rectify DNS settings first.

• Open Internet Explorer and browse to http://ApolloAPIServer/ApolloAPI/Index.html.

This should display a Apollo welcome page.

If you don’t see the welcome page, the IIS may not be started. In that case contact Barco support to rectify

the configuration.

2. Functionality

BARCO – Apollo 1.8 SOAP API – DOC-3338-2 – Reference manual – Revision 06 – Nov-2005

___________________________________________

2-2

• In Internet Explorer browse to http://ApolloAPIServer/ApolloAPI/DesktopManagement.wsdl.

This should display the WSDL of the Apollo DesktopManagement service. Similarly, the WSDL files for

DeviceManagement, ViewerManagement and InfraStructure can be checked.

If you don’t receive a valid response from the server, the virtual directory exposing the API may not be

configured correctly. In that case contact Barco support to rectify the configuration.

3. Sample Application for Microsoft VisualStudio.net

BARCO – Apollo 1.8 SOAP API – DOC-3338-2 – Reference manual – Revision 06 – Nov-2005

___________________________________________

3-1

3 Sample Application for Microsoft VisualStudio.net

This section explains how to setup MS VisualStudio.net for programming against the Apollo API and how to

create a sample application.

3.1 Client Side Setup

This assumes, that you already have setup MS VisualStudio.net 2003, walked through the “Building XML Web

Service Clients” tutorial (found at: ) and that you are familiar with the C# programming language.

There are two different approaches to create .Net clients for the Apollo API:

• the Wizard Method

• the Manual Method.

3.1.1.1 Using the Manual Method

The manual approach uses command line tools contained in the .Net framework to generate proxy classes for

the API without using VisualStudio.

The utilities for generating a proxy class from the WSDL files are:

• wsdl.exe

present in <installdir>\Microsoft Visual Studio .NET 2003\SDK\v1.1\Bin, the proxy generator

• csc.exe

present in C:\WINNT\Microsoft.NET\Framework\ v1.1.4322, the C# command line compiler.

The user can specify user defined names for the proxy class file and its corresponding dll say

DesktopManagement.cs and DesktopManagement.dll.

Once the proxy DLL is there, in the .Net IDE environment the user simply has to refer to it via the Project Menu’s

Add Reference option and start off with coding.

3.1.1.2 Using the Wizard Method

The wizard approach is used when VisualStudio is used to also generate the proxy classes. This is the

recommended way for most cases.

To access the Apollo API, in VisualStudio just Add Web Reference and select the WSDL file, in this case found at

http://ApolloApiServer/ApolloApi/DesktopManagement.wsdl. Then name the Web Reference, preferably the same as

the WSDL file, like “desktopmanagement”. Then the corresponding proxy class’s source file and its corresponding

dll are automatically generated.

In the project folder the proxy class’s source file resides with the name Reference.cs, f.i.:

ProjectFolder\WebReferences\DesktopManagement\References.cs

The proxy class’s dll resides at:

ProjectFolder\Obj\Debug\TempPE\WebReferences.DesktopManagement.Reference.cs.dll

3.2 Creating the Sample

The first example discusses the wizard approach and it is about invoking methods from the DesktopManagement

API. The code for this sample can be downloaded from the Apollo API server at:

http://ApolloApiServer/ApolloApi/Samples

3. Sample Application for Microsoft VisualStudio.net

BARCO – Apollo 1.8 SOAP API – DOC-3338-2 – Reference manual – Revision 06 – Nov-2005

___________________________________________

3-2

3.2.1 Wizard Approach

• Create a Visual C# application project to create a C# client program

• In VisualStudio.net select from the File menu: New Project | Visual C# Project | Windows Application

• Save the Project with the name f.i. ComprehensiveSample

• Add a new C# File

• In VisualStudio.net select from the File menu: New File | General |Text File.

Save the file with name AppMain.cs

• Add Web Reference

For each API you want to connect to from your project add a Web Reference for the WSDL file: Project | Add

Web Reference

• In the Add Web Reference dialog box , click the URL textbox and type the WDSL file path , in this

case: http://ApolloApiServer/ApolloApi/DesktopManagement.wsdl

• Click on the Go button. When the WSDL file is successfully downloaded from the Apollo API Server,

the description appears.

• Now specify a name in the web reference name textbox, to identify the WSDL definitions in .Net

environment. In this case name it “DesktopManagement”.

The dll's that are automatically created for each web reference will take the name as

desktopmanagement.dll.

• Now in the AppMain.cs file, to refer to classes present in the API, simply add in the beginning the

statement like

• Next, in AppMain.cs file write code to connect to each web service by creating an object of each web

reference and then invoke the required functions.

3.2.2 Manual Approach

• Set the PATH environment variable to include:

• wsdl.exe (present in <installdir>\Microsoft Visual Studio .NET 2003\SDK\v1.1\Bin)

• csc.exe (present in C:\WINNT\Microsoft.NET\Framework\ v1.1.4322)

• Generate a proxy class for the web service found at

• http://ApoloAPIServer/ApolloAPI/Infrastructure.wsdl

• http://ApoloAPIServer/ApolloAPI/DesktopManagement.wsdl

• http://ApoloAPIServer/ApolloAPI/ViewerManagement.wsdl

• http://ApoloAPIServer/ApolloAPI/DeviceManagement.wsdl

• Open a command prompt and change into the folder you want to develop the client in (f.i.

c:\Temp\SampleClient).

• at the command prompt enter (one command):

wsdl /l:cs /protocol:SOAP

http://ApolloApiServer/ApolloApi/DesktopManagement.wsdl

This will create a DesktopManagement.cs file in your folder

3. Sample Application for Microsoft VisualStudio.net

BARCO – Apollo 1.8 SOAP API – DOC-3338-2 – Reference manual – Revision 06 – Nov-2005

___________________________________________

3-3

• to compile the proxy class as Dll Library enter (again, one command):

csc /t:library /r:System.Web.Services.dll /r:System.Xml.dll

DesktopManagement.cs

This will generate a DesktopManagement.dll file.

• Using VisualStudio.Net create a C# application project to create a C# client program:

• from the File menu: New Project | Visual C# Project | Windows Application

• add a reference to DesktopManagement.dll by selecting from the Project menu

Add Reference, then browse to select DesktopManagement.dll

design a form and invoke DesktopManagement functions. Remember that C# is case sensitive.

• Now press the f5 key to run the project. The file AppMain.cs is compiled and executed.

4. Sample Application for Java

BARCO – Apollo 1.8 SOAP API – DOC-3338-2 – Reference manual – Revision 06 – Nov-2005

___________________________________________

4-1

4 Sample Application for Java

The following sections explain how to setup a Java environment to access the Apollo API and how to create a

client application. The creation of the client is a two-step process comparable to the .Net manual approach

described above. A first step creates the proxy classes, while the application as such is created in a separate step.

The code for this sample can be downloaded from the Apollo API server at:

http://ApolloApiServer/ApolloApi/Samples/Java

4.1 Client Side Setup

This section explains how to setup a development environment for accessing the Apollo API from the Java

programming language. The document describes the creation of the proxy classes with the Java IDE Borland

JBuiler9 and the free java IDE Eclipse 3.0. The SOAP functionality comes from the Systinet WaspSoap Toolkit in the

according versions 4.6 for JBuilder and 5.5 for Eclipse 3.0.

JBuilder9 Personal Edition can be downloaded from www.borland.com.

Eclipse can be downloaded from http://www.eclipse.org

Systinet WASP Developer can be downloaded from www.systinet.com.

The following steps are needed to install the Java development environment and the SOAP toolkit.

• Logon as local administrator.

• Install Eclipse 3.0 and Systinet WASP Developer 5.5

• Or install Borland JBuilder9 and Systinet WASP Developer 4.6

4.2 Creation of Proxy Classes with JBuilder9

The following steps will create a Jar file containing proxy classes to access the Apollo API.

• In the JBuilder environment create a Java Application project:

• Select from the File menu: New | General | Application

• Save the Project with the name f.i WaspSoapClient

• Download WSDL Files and create proxy classes from them, they will then get stored locally in

waspsoapclient\src folder.

• From the Wizards menu select the Download WSDL option. It will prompt for specifying the location

of WSDL file in URL textbox.

• In the URL textbox type: http://ApolloApiServer/ApolloApi/DesktopManagement.wsdl

• Click on Next button and the wizard will then prompt to specify the destination path. Enter the path

in local system where you want the WSDL file to reside. Instead of noname.wsdl specify

DesktopManagement.wsdl. Let the local WSDL path be under the src folder of the current project.

• Click on finish button to complete the process of wsdl downloads.

• Same for http://ApolloApiServer/ApolloApi/Infrastructure.wsdl

• Same for http://ApolloApiServer/ApolloApi/DeviceManagement.wsdl

• Same for http://ApolloApiServer/ApolloApi/ViewerManagement.wsdl

• Now in the Project Window, under the Downloads node one can see the WSDL files. Right click each one for

which we want to generate clients and select the Generate Web Service Client option.

• This will first prompt for client selection, select the default value.

• Next, it will prompt for the wsdl2java structure style property. Out of the 3 options (Structures, Java

Beans and Interfaces) select structures property and click on Next.

4. Sample Application for Java

BARCO – Apollo 1.8 SOAP API – DOC-3338-2 – Reference manual – Revision 06 – Nov-2005

___________________________________________

4-2

• Next, we have to specify the target specification. It has 2 options i.e the client package and project

the folder name. Set client package name (say for desktopmanagement) as

<packageprefix>.api.waspsoapclient.desktopmanagement. Note, that the sample uses

bcd.se.apollotest as a <packageprefix>, but this should be changed to fit into the client’s package

namespace. Set the project folder name (say for desktopmanagement) as DesktopManagement.

• Next, the wizard will prompt for the Client Type specification. Select the default option of Unsecure

Client.

• That’s it; now select the Finish button for completion of the client creation. Under

WaspSoapClient\src\<packageprefix>\api\waspsoapclient two folders are created, i.e.

DesktopManagement and DesktopManagementStruct. These contain the necessary proxy classes.

• In the end put all the proxy classes and other required library files under one jar file. In order to create the

jar file named WaspSoapClient.jar follow the following steps in the JBuilder environment for project

WaspSoapClient.jpx:

• From the Wizard Menu select the Archive Builder option. It will prompt you to select an Archive Type.

• From the options, select Basic Archive, this is the default and click on Next.

• For wizard steps, 2 and 3 let the default value be selected, i.e in step 2 you will be prompted to

enter the archive file name. By default the jar file will be named based on the project name, i.e for

the current example WaspSoapClientJB.jar. Let it be as it is.

• In step 3 it will prompt the parts of resources to be included in the archive, i.e classes and resources.

Select the 'All' option which is the default one.

• In step 4 select the library settings to "Always Include All resources and classes".

• In step 5 the prompt to include a manifest file or not is there, so simply let the default options

selected and click on finish button

• Now save the project. This completes the client proxy class creation in java. Next we will refer to these proxy

classes and invoke methods of different web services in a new project.

4.3 Creation of Proxy Classes with Eclipse 3.0.2

The following steps will create a Jar file containing proxy classes to access the Apollo API.

• In the Eclipse environment create a Java project:

• Choose the right workspace if you have more than one.

• Select from the File menu: New | Project

• Choose at the wizard window tree view: Systinet Web Services | Web Service Project

• Set the project name to WaspSoapClient and select Finish

• In the Package Explorer right click the project name and choose: New | Package.

• Set the package name i.E.: bcd.se.apollotest.api.waspsoapclient

• Download WSDL Files and create the proxy classes.

• Select the project name, right click and choose the menu entry: New | Other

• Choose at the wizard window tree view: Systinet Web Service | WSDL File from Internet, then NEXT

• In the tree view select a location for the WSDL file like: bcd.se.apollotest.api.waspsoapclient

• Set a name for the WSDL file to. DesktopManagementSoapPort, then NEXT.

• Insert the URL of the Apollo server with the WSDL files:

http://apolloapiserver/apolloapi/DesktopManagement.wsdl.

• Check the option “Download WSDLs ...”, then FINISH.

• Right click the WSDL file in the Package Explorer and select the menu option: Generate Interface.

• Set the location of the Interface Package (say for desktopmanagement) to

<packageprefix>.api.waspsoapclient.desktopmanagement. Note, that the sample uses

4. Sample Application for Java

BARCO – Apollo 1.8 SOAP API – DOC-3338-2 – Reference manual – Revision 06 – Nov-2005

___________________________________________

4-3

bcd.se.apollotest as a <packageprefix>, but this should be changed to fit into the client’s package

namespace.

• Set the location of the Structures Package on the same way, but add a “struct

structstruct

struct” at the service name

(<packageprefix>.api.waspsoapclient.desktopmanagementstruct

structstruct

struct). Click NEXT.

• The window “WSDL Part Selection” occurs. Select the option: “Generate interfaces for part of WSDL

file”.

• In the text box “Generate from Web Service Ports” select the current service by mouse click (here

DesktopManagement).

• Click the FINISH button to generate the proxy class.

• Same for InfrastructureSoapPort with:

URL: http://ApolloApiServer/ApolloApi/Infrastructure.wsdl

Interface Package: bcd.se.apollotest.api.waspsoapclient.infrastructure,

Structure Package: bcd.se.apollotest.api.waspsoapclient.infrastructurestruct

• Same for DeviceManagementSoapPort with:

URL: http://ApolloApiServer/ApolloApi/DeviceManagement.wsdl

Interface Package : bcd.se.apollotest.api.waspsoapclient.devicemanagement,

Structure Package: bcd.se.apollotest.api.waspsoapclient.devicemanagementstruct

• Same for ViewerManagementSoapPort with:

URL: http://ApolloApiServer/ApolloApi/ViewerManagement.wsdl

Interface Package: bcd.se.apollotest.api.waspsoapclient.viewermanagement

Structure Package: bcd.se.apollotest.api.waspsoapclient.viewermanagementstruct

• At least put all the proxy classes and other required library files under one jar file.

• In the Package Explorer, right click the current project and select the option Export.

• Choose the option JAR file, then NEXT.

• A wizard window opens. Select the resources to export. It is recommended selecting all files without

the WSDL and project files.

• Check the option “Export generated class files and resources” to export only the binaries.

• Set the path and name of the new JAR archive like WaspSoapClient.jar and click to finish.

• Next, we will refer to these proxy classes and invoke methods of different web services in a new project.

4.4 Creation of a Java Sample Application

The following section explains how to create a Java application project that uses the proxy classes created in the

previous step and invokes the various methods of desktopmanagement.

4.4.1 First ‘Hello world’ sample

4.4.1.1 Borland JBuilder9

• Create a new project in the JBuilder environment named HelloWorld.jpx. From the File menu select New |

General | Application. Save the project as HelloWorldjpx

• Create a new class named AppMain, i.e from the File menu select New Class.

Specify the package name as <packageprefix>.api.helloworld and the class name as AppMain and let other

options be the default ones.

• Add the WaspSoapClientJB.jar file created earlier in project library. From the Project menu select Project

Properties. Under the Paths Tab select the Required Libraries tab. Add a new library named “Apollo SOAP Api

using WASP Toolkit” which refers to the WaspSoapClientJB.jar library on the system.

4. Sample Application for Java

BARCO – Apollo 1.8 SOAP API – DOC-3338-2 – Reference manual – Revision 06 – Nov-2005

___________________________________________

4-4

4.4.1.2 Eclipse 3.0.x

• Choose the right workspace (if you have more than one).

• Select from the File menu: New | Project

• Choose at the wizard window tree view: Systinet Web Services | Web Service Project

• Set the project name to “HelloWorld”

• Select the project in the Package Explorer and open the context menu by a right click and select Properties.

• Select the option: Java Build Path | Libraries | Add External Jars…

• Brows to the previously generated WaspSoapClient.Jar file.

• Select OK

• In the Package Explorer, right click the project name and choose: New | Package.

• Set the package name as <packageprefix>.api.helloworld. In the delivered samples we are using

bcd.se.apollotest as packet prefix

• Select the project in the Package Explorer and open the context menu by a right click.

• In the Package Explorer, select the new package by right click and choose: New | Class.

• The Java Class wizard window occurs. Set a class name AppMain.java, check the option “public static void

main (…” and click Finish.

4.4.1.3 Both IDE’s

• Now write code to include the proxy classes and write methods to create instances of the proxy classes and

invoke various methods.

• Make sure to import the following classes like

import javax.xml.namespace.QName;

import org.systinet.wasp.webservice.Registry;

import org.systinet.wasp.webservice.ServiceClient;

import org.systinet.wasp.webservice.LookupException;

import bcd.se.apollotest.api.waspsoapclient.infrastructure.*;

• For connecting to a web service create a function for each web service. For ex. the following function

connects to Infrastructure.wsdl using the proxy classes.

• In the Class AppMain first declare the infrastructure client reference like

Static InfrastructureSoapPort mInfrastructure = null;

• Now create a function, which will link this client reference to the webservice.

private static void attachInfrastructure ()

throws LookupException

{

final String wsdlURI =

"http://ApolloApiServer/ApolloApi/Infrastructure.WSDL";

final String serviceURI = wsdlURI;

ServiceClient serviceClient;

serviceClient = ServiceClient.create (wsdlURI, InfrastructureSoapPort.class);

serviceClient.setServiceURL (serviceURI);

serviceClient.setWSDLServiceName (new

QName("http://tempuri.org/Infrastructure/wsdl/", "Infrastructure"));

serviceClient.setWSDLPortName("InfrastructureSoapPort");

mInfrastructure = (InfrastructureSoapPort) Registry.lookup(serviceClient);

}

Barco Apollo User guide

Related papers

Other documents