OxSvrSpt

1. General Description

The library OxSvrSpt.dll provides access to server functionality via a Microsoft-COM interface. The focus is on easy handling by the user and VB- and scripting-conform COM interfaces. The easy-to-use approach is used, which allows simple calls to be performed with few code lines. In multithreading applications, care must be taken that thread coordination regarding the execution of actions via OxSvrSpt is performed.

The following properties are supported:

  • Error handling via COM error (IErrorInfo)

  • All occurred errors are thrown as COM errors. If a method call returns multiple errors (z. B. calling a server job), the first error is thrown as a COM error and the remaining errors are available in a collection.

  • Transparent use of Base64 parameter

  • The processing of the Base64 parameter of the server is completely taken over by OxSvrSpt. For this purpose, stream and XML access methods are provided to the user.

  • Automatic encoding and decoding of binary parameters (BASE64)

  • The data passed by the user to the OxSvrSpt library is automatically encoded for transmission to the server in MIME-BASE-64 and decoded when retrieving data from the server. The user no longer comes into contact with the encoding.

  • Encoding and decoding of XML data by library

  • Through the XML properties of the parameter and FileParameter interfaces, there is the possibility to read and set the basic string representation (BSTR) of XML data. The OxSvrSpt library takes care of the correct encoding and decoding into the corresponding binary representation (UTF-8, UTF-16, …​). The stream methods of these interfaces also provide the possibility to process the data directly via an IStream interface. It is therefore possible, for example, to load parameters directly into an MSXML-DOM document or take them from such a document.

  • Automatic encoding of password via module

  • For login, there is the option to pass the password encoded or unencoded. The necessary conversion for transmission to the server is taken over by the OxSvrSpt library.

A configured two-factor authentication is not included.

  • Collections that can be used with ForEach

  • All COM collections are ForEach-capable. This makes it possible to iterate from Visual Basic, scripting environments and .net through these.

  • Correct processing of collections and parameters in the debugger

  • In debug environments that directly access the properties of COM objects and display them (e.g. Visual Basic), it is ensured that the stream accesses used do not get disturbed. The collections are VB-compatible, which makes it possible to view the elements in the VB debugger.

  • Return parameters are created by the called property or method

  • All return parameters are made available so that creation is done via a method of the OxSvrSpt library. It is not necessary to pass a variable to fill into the library from a COM scripting environment. The server object is the only creatable object except for the helper object. All other interfaces are provided by this, or subordinate interfaces.

  • Simple processing of notifications

  • For processing notifications, an event interface is available that takes over the processing of input and output parameters in an equivalent way to the job interface.

  • Methods for reading and writing ASCII data from streams

  • When trying to serialize basic character strings from Visual Basic or COM-based scripting environments, the data is processed as widechars. The methods provided allow reading and writing data that is not XML as ASCII from Base64 parameters.

2. Modules

2.1. Including the Library

This section shows the use of the OxSvrSpt library from different programming languages. Depending on the programming language and development environment used, the possibilities for accessing the library differ.

Visual Basic

To use OxSvrSpt via the type library, the enaio® server access library must be included via the "References" menu item of the development environment.

Creation is done via the following code:

Private m_oServer As new OxSvrSpt.Server

The component can also be included using late binding. The source code for this corresponds to the VB-Script code.

Visual Basic Script

In VB-Script, the server object can be created as follows:

Dim oServer
Set oServer = CreateObject( "OxSvrSpt.Server" )

Visual C++

For using the OxSvrSpt library in Visual C++, the use of the import directive is recommended. The following code snippet shows this import. This should be done at a central location, e.g. StdAfx.h.

// warning C4192: automatic exclusion of 'IStream'
// during import of type library 'OxSvrSpt.tlb'
#pragma warning ( disable: 4192 )
#import "OxSvrSpt.dll" raw_method_prefix("raw_") rename_namespace( "OxSvrSpt" )
#pragma warning ( default: 4192 )

For use, the high methods should be used instead of the raw methods. To avoid confusion, the raw functions are therefore provided with the prefix raw_ in the above import directive. The high methods map COM errors automatically to _com_error exception handling. In addition, these ensure that passed basic character strings are of the correct type. The following code snippet shows the direct use of a widechar string as a parameter, instead of a basic string. Since access to a basic string in C++ corresponds to a WIDECHAR string, this is compilable and works as long as the COM client and the COM server are in the same apartment.

However, this should not be assumed!

Such a call can lead to hard-to-locate errors.

HRESULT Test( BSTR Message );
...
HRESULT hr = Test( L"irgendwas" );

If instead of the raw method the high method is used, the _bstr_t class takes care of correct processing.

HRESULT Test(_bstr_t Message );
...
HRESULT hr = Test( L"irgendwas" );

Note:

When implementing high methods without retval return value, the import directive declares these methods as HRESULT instead of void. This HRESULT never returns an error value, since in case of an error a _com_error exception is thrown. The structure of these methods resembles that of the raw functions. For this reason, to avoid confusion, the raw_method_prefix should be used.

The creation of the object should be done via the constructor of the IServerPtr and not via the CreateInstance method, since the latter does not throw a _com_error exception on failure. In this case, it is necessary to evaluate the HRESULT value yourself to get a meaningful error message.

try {
OxSvrSpt::IServerPtr spServer( __uuidof( OxSvrSpt::Server ));
}
catch ( _com_error& ex ) {
// here error handling occurs
}

Alternatively, the creation of the IServer object can also be done via the name of the Co-class. This corresponds roughly to late binding when creating objects in Visual Basic.

try {
OxSvrSpt::IServerPtr spServer( "OxSvrSpt::Server" ));
}
catch ( _com_error& ex ) {
// here error handling occurs
}

Microsoft C#

To use the component, the reference to enaio® server access library must be added in Microsoft Visual Studio. For this, click on Project - Add Reference - COM . Then the namespace OxSvrSpt can be included with the using directive.

Server server = new Server();

2.2. Login

This section shows the use of the ISession object in different programming languages. Login methods are presented with which you can log in using an unencrypted and encrypted password, a session GUID and the NT user name to the enaio®-server.

Possibilities for login

To log into the system, an object of the class IServer must have been created. This provides methods, such as Login(), which you can use to log in. Upon successful authentication, the methods return an ISession object. If authentication fails, a COM exception is thrown. If you pass empty strings for the parameters " username " and " password ", then the library attempts to log in with the NT user. Automatic login is possible, if this has been activated in enaio® administrator. NTLM authentication is not yet implemented.

  • The Login() method is used to log in the specified user to the specified server.

  • The LoginGUID() method is used to log in with an existing SessionGUID.

  • The LoginBalanced() method is used to log in to a group of servers. Each possible server in the list consists of the server name, port and weighting. The weighting indicates with what probability the connection to the associated server is established. The weights should not exceed 100 in total.

  • The OpenSession() method is used to log in to an existing DefaultSession. DefaultSessions can be created using the previously described methods by setting the parameter DefaultSession to True.

Visual Basic and VB-Script

The Login() method receives the parameters " username ", " password ", " server " and " port " as input. In this case, " PasswordType " and DefaultSession are automatically set to false.

Dim session As session
' Login of a user to the specified server
Set session = server.Login("root", "optimal", "localhost", "4000")
' Login via an existing SessionGUID
Set session = server.LoginGUID("D57D21256EFB4C91B79EDD5A4928400B", "localhost",
"4000")
' Login of a user to a group of servers
Set session = server.LoginBalanced("root", "optimal",
"localhost#4000#90;10.1.3.100#4600#10")

Visual C++

In C, the parameters " `PasswordType` " and " `DefaultSession` " cannot be omitted, since C does not support default values. The following examples show login with an encrypted password.

// Login of a user to the specified server
OxSvrSpt::ISessionPtr spSession = spServer->Login("root", "HB016016116515215614215500000000000000000000000000", "localhost", "4000", OxSvrSpt::PasswortTypeEnum::pwEncrypted, false );

// Login via an existing SessionGUID
OxSvrSpt::ISessionPtr spSession = spServer>LoginGUID("D57D21256EFB4C91B79EDD5A4928400B","localhost", "4000", false );

// Login of a user to a group of servers
OxSvrSpt::ISessionPtr spSession = spServer->LoginBalanced("root", "HB016016116515215614215500000000000000000000000000", "localhost#4000#90;10.1.3.100#4600#10",OxSvrSpt::PasswortTypeEnum::pwEncrypted, false );

// Create a DefaultSession (parameter DefaultSession = true)
OxSvrSpt::ISessionPtr spDefaultSession = spServer->Login("root", "HB016016116515215614215500000000000000000000000000", "localhost", "4000", OxSvrSpt::PasswortTypeEnum::pwEncrypted, true );

// Login to a DefaultSession
OxSvrSpt::ISessionPtr spSession = spServer->OpenSession((bstr_t)spDefaultSession->Properties->Item["SessionGUID"]->Value, OxSvrSpt.OpenSession);

Visual C#

In C#, the parameters " PasswordType " and " DefaultSession " cannot be omitted. In this example, login with the NT user name should be made, which is why empty strings are passed for the parameters " username " and " password ".

// Login of a user to the specified server
Session session = server.Login("","","localhost", "4000", PasswortTypeEnum.pwNotEncrypted, false );

// Login via an existing SessionGUID
Session session = server.LoginGUID("D57D21256EFB4C91B79EDD5A4928400B","localhost", "4000", false );

// Login of a user to a group of servers
Session session = server.LoginBalanced("", "", "localhost#4000#90;10.1.3.100#4600#10", PasswortTypeEnum.pwNotEncrypted, false );

// Create a DefaultSession (parameter DefaultSession = true)
Session defaultSession = server.Login("root","optimal","localhost", "4000", PasswortTypeEnum.pwNotEncrypted, true );

// Login to a DefaultSession
Session session = server.OpenSession(defaultSession.Properties["SessionGUID"].Value.ToString(), "OxSvrSpt.OpenSession");

2.3. License Management

For checking and using licenses, the ILicenses collection is available in the ISession object. Through this, the licenses to be used on the server can be logged in, logged out and checked. All logged-in licenses are kept in the collection.

/*
JavaScript version
This enables the use of COM exceptions compared to the VBS version. When an error occurs, the program flow
is interrupted and jumps to error handling.
*/
try
{
var oServer, oSession, oJob;
// Create access object and log in
oServer = new ActiveXObject( "OxSvrSpt.Server" );
oSession = oServer.Login( "root", "optimal", "localhost", "4000" );
// Add and delete licenses
oSession.Licenses.Add( "ASC" );
oSession.Licenses.Delete( "ASC" );
oSession.Licenses.Add( "ASC" );
// worked: o)
WScript.Echo( "ok" );
}
catch( ex )
{
// Display occurred errors
WScript.Echo( ex.description );
}

2.4. Server Events

Description

You have the option to be informed by the server about certain events via Notifications.

VB

In Visual Basic, Notifications are available through the event mechanism as shown in the following example.

Private WithEvents m_oSession As OxSvrSpt.Session
Private m_oServer As OxSvrSpt.Server
public sub Start()
    m_oServer.Properties("NotifyNeeded") = True
    Set m_oSession = m_oServer.Login(,, "localhost", "4000")
    end sub
    Private Sub m_oSession_Notify(Job As OxSvrSpt.INotifyJob)
    On Error GoTo ErrTrap
    Dim strFileXML As String
    strFileXML = Job.InputFileParameters(1).XML
    ' Return parameters
    Job.OutputParameters.AddNewIntegerParameter "test", 100
    Job.OutputParameters.AddNewStringParameter "meier", "huhu"
    Exit Sub
    ErrTrap:
    MsgBox Err.Description
    End Sub

VBScript

If you want to use Notifications in a scripting host environment (VB-Script as vbs), you must create the instance via the CreateObject() method of the WScript environment.

Dim oServer
Set oServer = WScript.CreateObject( "OxSvrSpt.Server", "oServer_" )

If the IServer object is created via the WScript host, there is the option to specify a prefix for event functions. Through this mechanism, the Notifications can be caught.

Furthermore, the Callback functionalities of the OxSvrCom library are available through the methods CreateJobSink() and CreateJobSink() of the ISession interface.

Dim oServer, oSession
Set oServer = WScript.CreateObject( "OxSvrSpt.Server", "oServer_" )
' Notifications should be used
oServer.Properties("NotifyNeeded") = True
' Use auto-login
Set oSession = oServer.Login( "", "", "localhost", "4000" )

' ...

'
' This function is called by the server object when a notification arrives
' within the specified idle time.
'
' @param oJob
'   Contains the data for calling the notification.
'   This corresponds to the job object of the session. The only
'   difference is that instead of input parameters, output parameters are used
'   to create parameters.
'
Sub oServer_Notify( oJob )
    Dim strText
    ' Display name of notification
    strText = "Name: " & oJob.Name & vbCrLf
    ' Display all input parameters
    strText = strText & " Parameter: " & vbCrLf
    Dim oParameter
    For Each oParameter In oJob.InputParameters
        strText = strText & "  " & oParameter.Name & " - " & _
            CStr( oParameter.Value ) & vbCrLf
    Next
    ' Write result to a text box
    MsgBox strText
End Sub

2.5. XML Processing

Depending on the XML encoding used, the XML data differs in its binary representation.

Example for determining object definition

JavaScript version

/*
JavaScript version
This enables the use of COM exceptions compared to the VBS version. When an error occurs, the program flow
is interrupted and jumps to error handling.
*/
try
{
var oServer, oSession, oJob;
// Create access object and log in
oServer = new ActiveXObject( "OxSvrSpt.Server" );
oSession = oServer.Login( "root", "optimal", "localhost", "4000" );
// Create job for determining object definition
oJob   = oSession.NewJob( "dms.GetObjDef" );
// Set request parameters
oJob.InputParameters.AddNewIntegerParameter( "Flags", 0 );
// Execute job
oJob.Execute();
// Get XML from output file
// When reading, the XML character encoding
// is taken into account.
// After completion of this call, the passed
// file is automatically deleted.
WScript.Echo( oJob.OutputFileParameters(1).XML );
}
catch( ex )
{
// Display occurred errors
WScript.Echo( ex.description );
}

VB-Script version

Option Explicit
Dim oServer, oSession, oJob,o
Set oServer = CreateObject( "OxSvrSpt.Server" )
set oSession = oServer.Login( "root", "optimal", "localhost", "4000" )
set oJob   = oSession.NewJob( "dms.GetObjDef" )
oJob.InputParameters.AddNewIntegerParameter "Flags", 0
oJob.Execute
msgbox oJob.OutputFileParameters(1).XML,,"Object definition"

2.6. Binary Data Processing

For processing binary data in input and output parameters, several options are available. Both the IParameter - and the IFileParameter -objects provide two different methods for this.

  • 1. Access via chunks (byte arrays)

  • 2. Access via a stream ( IStream )

'
' Example script to read binary data byte by byte via the
' GetChunk method of a parameter.
'
Option Explicit
Dim oServer, oSession, oJob, oFileParameter
Set oServer = CreateObject("OxSvrSpt.Server")
set oSession = oServer.Login("root", "optimal", "localhost", 4000)
Set oJob   = oSession.NewJob("dummy")
Set oFileParameter = oJob.InputFileParameters.AddTempFile()
oFileParameter.xml = "<?xml version='1.0' encoding='utf-16' ?><abc>äöü</abc>"
' Set stream to beginning position
oFileParameter.ResetStream
Dim abReadData
abReadData = oFileParameter.GetChunk(oFileParameter.ActualSize)
Dim cPos
For cPos = LBound(abReadData) + 1 To UBound(abReadData)
Dim bData
bData = Ascb(Midb(abReadData, cPos, 1))
WScript.Echo(cPos & ":" & bData)
next
WScript.Echo("finished")

2.7. Error Handling

In all error cases, the OxSvrSpt library throws a COM error. In addition, the errors are also added to the IError collection in both the IServer - and the IJob -objects. In both cases, it is possible that more than one error is returned. The COM error corresponds to the first error in the IError collection.

2.8. Structure Plan

The following diagrams show the structure of OxSvrSpt:

Legend for the flowchart

OxSvrSpt library

Session object

Job object

Properties D collection

Licenses collection

OutputParameters D collection

InputParameters collection

OutputFileParameters collection

InputFileParameters collection

Errors collection

Parameter object

FileParameter object

2.9. Attaching Watermarks to PDF Documents

In addition to the watermark printing designation of PDF documents via the settings in enaio® administrator, there is the possibility to attach watermarks using extended capabilities. For this, the target format 'pdf' must be specified and the Job parameter 'Watermark' set to 1. All following parameters consist of a prefix and a postfix, where the parameter 'HeaderText' has the prefix 'Header' and the postfix 'Text'. The parameters are described in detail below:

Four areas can be defined for text input with the following parameter prefixes: 'Header', 'Footer', 'Side' and 'Center'.

The following parameter postfixes are possible, each of which must use one of the above prefixes. All parameter postfixes are optional, but at least one ' *Text ' parameter must be specified so that the extended watermark is applied, otherwise the enaio® administrator settings are used. The postfixes are listed below:

Text (STRING):

Text to be applied. If no text is specified, all other entries for the corresponding watermark type are ignored and no text is applied.

The following replacement variables are possible in the specified text:

Variable Description

TIME current time

DATE current date

USER username

USER-FULL full username

COMPUTER-IP IP address

COMPUTER-GUID GUID of computer

COMPUTER-NAME name of computer

TextColor (INT):

0 – 7 (default is 0) with the following values: Value Description

0 Black

1 White

2 Yellow

3 Red

4 Green

5 Magenta

6 Cyan

7 Blue

Alternatively:

TextColorRGB (STRING): 0-255,0-255,0-255 (R,G,B values for a color separated by comma)

Font (STRING): Helvetica…, Times…, or Courier… (default is Helvetica)

FontBold (INT): 0 or 1 ( 1→ Bold, 0 → Standard)

FontItalic (INT): 0 or 1 ( 1→ Italic, 0 → Standard)

FontSize (INT): Font size in points (default is 10)

The following parameters can be used to set the position of the text:

Position (INT): 0-8 (default is 0) for 'Header' 0, for 'Footer' 1, for 'Side' 4 and for 'Center' 8

Value Description

0 Top-left

1 Bottom-left

2 Top-right

3 Bottom-right

4 Center-left

5 Center-right

6 Center-top

7 Center-bottom

8 Center-center

OffsetX (INT): (default is 0) Offset in mm relative to left edge of sheet.

OffsetY (INT): (default is 0) Offset in mm relative to top edge of sheet.

PlaceType (INT): 0-2 (default is 0) 0 → All pages, 1 → odd pages, 2→ even pages

FillStyle (INT): 0-2 (default is 0) 0 → Filled, 1 → shadow outline, 2 → filled shadow outline

Angle (INT): 0-360 (default is 0) Rotation in degrees

Example of a call:

Set oServerJob = o.CreateServerJob("cnv.ConvertDocument")
oServerJob.AddFile "myfile" (file to be converted)
oServerJob.AddInputParameter "DestinationFormat", "pdf", 1
oServerJob.AddInputParameter "HeaderText", "Header line", 1
oServerJob.AddInputParameter "HeaderFont", "Courier", 1
oServerJob.AddInputParameter "HeaderFontSize", "10,0", 4
oServerJob.AddInputParameter "HeaderTextColor", "3", 2
oServerJob.AddInputParameter "FooterText", " Created by #USER#, #DATE#,
#TIME#", 1
oServerJob.AddInputParameter "FooterFontSize", "14,0", 4
oServerJob.AddInputParameter "FooterFontBold", "1", 2
oServerJob.AddInputParameter "FooterFontItalic", "1", 2
oServerJob.AddInputParameter "FooterTextColorRGB", "255,0,0", 1

Note: Instead of prefixes 'Header' and 'Footer' as in this example, 'Side' or 'Center' are also possible.

Example for positioning with type 'Center':

oServerJob.AddInputParameter "CenterAngle", "45", 2
oServerJob.AddInputParameter "CenterOffsetX", "-10", 2
oServerJob.AddInputParameter "CenterOffsetY", "10", 2
oServerJob.AddInputParameter "CenterPlaceType", "1", 1
oServerJob.AddInputParameter "CenterFillStyle", "2", 1

Note: Care must be taken to observe case sensitivity. ( Job parameters are generally case sensitive).

3. Data Structures

3.1. _INotificationEvents

Description:

_INotifiactionEvent is an event interface for processing Notifications.

import "OxSvrSpt.idl"

Public Methods:

void Notify([in, out] INotifyJob **Job)

Parameters:

[in, out]: Job interface for accessing the input and output parameters of the notification. This behaves equivalently to the IJob interface.

4. Class Hierarchy

  • _INotificationEvent

  • IError

  • IErrors

  • INotifyErrors

  • IFileParameter

  • IHelper

  • IInputFileParameters

  • INotifyOutputFileParameters

  • IInputParameters

  • INotifyOutputParameters

  • IJob

  • ILicenses

  • ILogger

  • INotifyJob

  • IOutputFileParameters

  • INotifyInputFileParameters

  • IOutputParameters

  • IInputParameters

  • IParameter

  • IProperties

  • IProperty

  • IServer

  • ISession