 API browser of generalnotification451 COM module
Interface version: | 4.51
Interface date: | 28 Sep 2018

The GeneralNotificationManager is an ATL COM module that provides methods to generate an email like structured message exchange between two partners. The produced XML infoset is transported electronically to the recipient and optionally can be signed and/or encrypted.

Structured message exchange means that the message thread is uniquely identified by the notification object reference and optionally the target of the message exchange can be defined by a dependent object reference of type credit, invoice, reminder, MCD, or form.

Furthermore, by using the formOID attribute of the message a form process can be initiated at any point of the message exchange. Additionally, a infinite number of documents of a well defined type (.jpg, .png and .pdf) can be attached and transported in each step of the communication.

space
Interfaces | 4 interface
IAddress | The utility interface IAddress is available for setting and/or retrieving structured address data.
IGeneralNotificationManager | The main interface IGeneralNotificationManager -creatable in its own right- all necessary methods to produce a new message thread or reply to a received one.
IGeneralNotificationRequest | The IGeneralNotificationRequest is used for producing a new message thread or to formulate a reply to a prior load message.
IGeneralNotificationResponse | The interface IGeneralNotificationResponse allows to read back all data that have been defined with the IGeneralInvoiceRequest interface or by loading a previously generated XML infoset.
Types
type definitions | List of all used builtin, composite and enumeration types
Important documents about the usage and handling
Document | General usage of the generalNotification451 COM module - an overview
Document | Overview of changes when moving from generalNotification450 to generalNotification451
Document | What to do in a 64bit environment - is there a 64bit Sumex1 COM dll?
Document | Overview of the concept of "Object reference"
Document | Notes about the signature part of the XML infoset
Document | Notes about the encryption part of the XML infoset
Document | Syntax of the printTemplate variable of the Print method
Document | How to generate a PDF archive file of a generalNotification
Document | VB code snippet for using the generalNotification451 COM module
Document | generalNotificationManagerServer451: Introduction, overview and usage of the Restful Webservice Server
04.04.2020 - API Patch | Documentation: query/check the reachability of a recipient bstrToEAN

© by sumex1.net - all rights reserved


  • generalnotification451
  • IAddress

IAddress interface |  | V4.51/28 Sep 2018
With the IAddress interface address data can be set and/or retrieved. The address of a person is set by the method SetPerson whereas a company address is entered by the method SetCompany. Before setting a new address the interface has to be initialized by the method Initialize. |  | space
space
Methods |  | 16 methods
AddPhone | Adds a structured phone number |
GetAbortInfo | Gets the abort information string with the error coded in the module language |
GetCompany | Retrieves the company's naming part of the address |
GetFax | Retrieves the structured fax number. |
GetFirstPhone | Retrieves the first phone number information |
GetNextPhone | Retrieves the next phone number information |
GetOnline | Retrieves the structured online part of the address |
GetPerson | Retrieves the person's naming part of the address |
GetPhones | Method for collecting all phone numbers covered by the address and returned as JSON array |
GetPostal | Retrieves the structured postal address part of the address |
Initialize | Initializes all address variables |
SetCompany | Sets the company's naming part of the address |
SetFax | Sets a structured fax number |
SetOnline | Sets the structured online part of the address. |
SetPerson | Sets the person's naming part of the address |
SetPostal | Sets the structured postal address part |
space
Properties |  | 2 properties
[put] DestructAddress | Destructs/invalidates this IAddress interface instance |
[get] Type | GetType returns the type of address either enAddressPerson or enAddressCompany if an address is defined at all |
space |


  • IAddress
  • AddPhone

IAddress::AddPhone method |  |  | space
Adds a structured phone number. The Swiss international calling code +41 is filtered out in the printing. If the main software does not support structured pone numbers then all data is supplied in the bstrNumber variable. However, +41 is then no longer filtered. |  |  |
space
Restful webservice calling syntax |  |  |
[POST] | /baseURL/ IAddress/AddPhone
[JSON input data] | pIAddress: bstrNumber: bstrLocalCode: bstrInternationalCode: bstrExt: | longValue, //interface address "utf8StringValue", "utf8StringValue", "utf8StringValue", "utf8StringValue"
[JSON result data] | pbStatus: | booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
C/C++ calling syntax |  |  |
HRESULT AddPhone( | BSTR BSTR BSTR BSTR VARIANT_BOOL | bstrNumber, bstrLocalCode, bstrInternationalCode, bstrExt, *pbStatus); |
[C/C++ return value] | S_OK | This value is returned if the function call was successful. |
 | S_FALSE | This value is returned if the end of an iteration is reached |
 | E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions. |
space
Calling argument description |  |  |
[in] BSTR | bstrNumber | The pure phone number part of the telephone number. It is possible to set the full telephone number in this variable and leave the other parts of the telephone number empty |
[in] BSTR | bstrLocalCode | The local area code part of the telephone number. |
[in] BSTR | bstrInternationalCode | The international calling code part of the telephone number. |
[in] BSTR | bstrExt | The optional extension number part of the telephone number. |
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE then an error occurred and GetAbortInfo should be called to retrieve the error string. |
space |


  • IAddress
  • GetAbortInfo

IAddress::GetAbortInfo method |  |  | space
Gets the abort information string with the error coded in the module language. Call this method whenever the returned pbStatus variable of the primarily called method is VARIANT_FALSE and this primarily called method is not an iterator (GetFirst/GetNext methods). In the later case VARIANT_FALSE signals the end of data. |  |  |
space
Restful webservice calling syntax |  |  |
[POST] | /baseURL/ IAddress/GetAbortInfo
[JSON input data] | pIAddress: | longValue, //interface address
[JSON result data] | pbstrAbort: pbStatus: | "utf8StringValue", booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
C/C++ calling syntax |  |  |
HRESULT GetAbortInfo( | BSTR VARIANT_BOOL | *pbstrAbort, *pbStatus); |
[C/C++ return value] | S_OK | This value is returned if the function call was successful. |
 | S_FALSE | This value is returned if the end of an iteration is reached |
 | E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions. |
space
Calling argument description |  |  |
[out] BSTR | *pbstrAbort | Abort information string coded in the module language. |
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE then an error-in-error situation occurred. |
space |


  • IAddress
  • GetCompany

IAddress::GetCompany method |  |  | space
Retrieves the company's naming part of the address. Call the property GetType first to test if GetPerson or GetCompany should be called. |  |  |
space
Restful webservice calling syntax |  |  |
[POST] | /baseURL/ IAddress/GetCompany
[JSON input data] | pIAddress: | longValue, //interface address
[JSON result data] | pbstrCompanyName: pbstrDepartment: pbstrSubaddressing: pbStatus: | "utf8StringValue", "utf8StringValue", "utf8StringValue", booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
C/C++ calling syntax |  |  |
HRESULT GetCompany( | BSTR BSTR BSTR VARIANT_BOOL | *pbstrCompanyName, *pbstrDepartment, *pbstrSubaddressing, *pbStatus); |
[C/C++ return value] | S_OK | This value is returned if the function call was successful. |
 | S_FALSE | This value is returned if the end of an iteration is reached |
 | E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions. |
space
Calling argument description |  |  |
[out] BSTR | *pbstrCompanyName | The company's name. |
[out] BSTR | *pbstrDepartment | The optional department part of the company. |
[out] BSTR | *pbstrSubaddressing | The optional subaddressing information, e.g. a "c/o" like information as defined by the Post |
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE then an error occurred and GetAbortInfo should be called to retrieve the error string. |
space |


  • IAddress
  • GetFax

IAddress::GetFax method |  |  | space
Retrieves the structured fax number. |  |  |
space
Restful webservice calling syntax |  |  |
[POST] | /baseURL/ IAddress/GetFax
[JSON input data] | pIAddress: | longValue, //interface address
[JSON result data] | pbstrNumber: pbstrLocalCode: pbstrInternationalCode: pbstrExt: pbStatus: | "utf8StringValue", "utf8StringValue", "utf8StringValue", "utf8StringValue", booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
C/C++ calling syntax |  |  |
HRESULT GetFax( | BSTR BSTR BSTR BSTR VARIANT_BOOL | *pbstrNumber, *pbstrLocalCode, *pbstrInternationalCode, *pbstrExt, *pbStatus); |
[C/C++ return value] | S_OK | This value is returned if the function call was successful. |
 | S_FALSE | This value is returned if the end of an iteration is reached |
 | E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions. |
space
Calling argument description |  |  |
[out] BSTR | *pbstrNumber | The pure fax number part of the full fax number. It is possible that the full fax number is returned in this variable and the other parts of the fax number left empty. |
[out] BSTR | *pbstrLocalCode | The local area code part of the fax number. |
[out] BSTR | *pbstrInternationalCode | The international calling code part of the fax number. |
[out] BSTR | *pbstrExt | The extension number part of the fax number. |
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE then an error occurred and GetAbortInfo should be called to retrieve the error string. |
space |


  • IAddress
  • GetFirstPhone

IAddress::GetFirstPhone method |  |  | space
Retrieves the first phone number information. VARIANT_FALSE is returned if the end of the phone list is reached. |  |  |
space
Restful webservice calling syntax |  |  |
[POST] | /baseURL/ IAddress/GetFirstPhone
[JSON input data] | pIAddress: | longValue, //interface address
[JSON result data] | pbstrNumber: pbstrLocalCode: pbstrInternationalCode: pbstrExt: pbStatus: | "utf8StringValue", "utf8StringValue", "utf8StringValue", "utf8StringValue", booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
C/C++ calling syntax |  |  |
HRESULT GetFirstPhone( | BSTR BSTR BSTR BSTR VARIANT_BOOL | *pbstrNumber, *pbstrLocalCode, *pbstrInternationalCode, *pbstrExt, *pbStatus); |
[C/C++ return value] | S_OK | This value is returned if the function call was successful. |
 | S_FALSE | This value is returned if the end of an iteration is reached |
 | E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions. |
space
Calling argument description |  |  |
[out] BSTR | *pbstrNumber | The pure phone number part of the full telephone number. It is possible that the full telephone number is returned in this variable and the other parts of the telephone number left empty. |
[out] BSTR | *pbstrLocalCode | The local area code part of the telephone number. |
[out] BSTR | *pbstrInternationalCode | The international calling code part of the telephone number. |
[out] BSTR | *pbstrExt | the extension number part of the telephone number. |
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE the end of data is reached |
space |


  • IAddress
  • GetNextPhone

IAddress::GetNextPhone method |  |  | space
Retrieves the next phone number information. VARIANT_FALSE is returned if the end of the phone list is reached |  |  |
space
Restful webservice calling syntax |  |  |
[POST] | /baseURL/ IAddress/GetNextPhone
[JSON input data] | pIAddress: | longValue, //interface address
[JSON result data] | pbstrNumber: pbstrLocalCode: pbstrInternationalCode: pbstrExt: pbStatus: | "utf8StringValue", "utf8StringValue", "utf8StringValue", "utf8StringValue", booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
C/C++ calling syntax |  |  |
HRESULT GetNextPhone( | BSTR BSTR BSTR BSTR VARIANT_BOOL | *pbstrNumber, *pbstrLocalCode, *pbstrInternationalCode, *pbstrExt, *pbStatus); |
[C/C++ return value] | S_OK | This value is returned if the function call was successful. |
 | S_FALSE | This value is returned if the end of an iteration is reached |
 | E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions. |
space
Calling argument description |  |  |
[out] BSTR | *pbstrNumber | The pure phone number part of the full telephone number. It is possible that the full telephone number is returned in this variable and the other parts of the telephone number left empty. |
[out] BSTR | *pbstrLocalCode | The local area code part of the telephone number. |
[out] BSTR | *pbstrInternationalCode | The international calling code part of the telephone number. |
[out] BSTR | *pbstrExt | the extension number part of the telephone number. |
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE the end of data is reached |
space |


  • IAddress
  • GetOnline

IAddress::GetOnline method |  |  | space
Retrieves the structured online part of the address. Empty variables are returned if there is no online information available. |  |  |
space
Restful webservice calling syntax |  |  |
[POST] | /baseURL/ IAddress/GetOnline
[JSON input data] | pIAddress: | longValue, //interface address
[JSON result data] | pbstrEMail: pbstrUrl: pbStatus: | "utf8StringValue", "utf8StringValue", booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
C/C++ calling syntax |  |  |
HRESULT GetOnline( | BSTR BSTR VARIANT_BOOL | *pbstrEMail, *pbstrUrl, *pbStatus); |
[C/C++ return value] | S_OK | This value is returned if the function call was successful. |
 | S_FALSE | This value is returned if the end of an iteration is reached |
 | E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions. |
space
Calling argument description |  |  |
[out] BSTR | *pbstrEMail | A relevant email address. |
[out] BSTR | *pbstrUrl | A relevant URL. |
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE then an error occurred and GetAbortInfo should be called to retrieve the error string. |
space |


  • IAddress
  • GetPerson

IAddress::GetPerson method |  |  | space
Retrieves the person's naming part of the address. Call the property GetType first to test if GetPerson or GetCompany should be called. |  |  |
space
Restful webservice calling syntax |  |  |
[POST] | /baseURL/ IAddress/GetPerson
[JSON input data] | pIAddress: | longValue, //interface address
[JSON result data] | pbstrFamilyname: pbstrGivenname: pbstrSalutation: pbstrTitle: pbstrSubaddressing: pbStatus: | "utf8StringValue", "utf8StringValue", "utf8StringValue", "utf8StringValue", "utf8StringValue", booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
C/C++ calling syntax |  |  |
HRESULT GetPerson( | BSTR BSTR BSTR BSTR BSTR VARIANT_BOOL | *pbstrFamilyname, *pbstrGivenname, *pbstrSalutation, *pbstrTitle, *pbstrSubaddressing, *pbStatus); |
[C/C++ return value] | S_OK | This value is returned if the function call was successful. |
 | S_FALSE | This value is returned if the end of an iteration is reached |
 | E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions. |
space
Calling argument description |  |  |
[out] BSTR | *pbstrFamilyname | The family name (or last name) of the person. |
[out] BSTR | *pbstrGivenname | The given name (or first name) of the person. |
[out] BSTR | *pbstrSalutation | The optional salutation of the person. |
[out] BSTR | *pbstrTitle | The optional title of the person. |
[out] BSTR | *pbstrSubaddressing | The optional subaddressing information, e.g. a "c/o" like information as defined by the Post |
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE then an error occurred and GetAbortInfo should be called to retrieve the error string. |
space |


  • IAddress
  • GetPhones

IAddress::GetPhones method |  |  | space
This method has a Restful Webservice representation only! Method for collecting all phone numbers covered by the address and returned as JSON array. Please note that IAddress::GetPhones takes over the functionality of the iterator pair IAddress::GetFirstPhone / IAddress::GetNextPhone with a single call, making the latter superfluous. |  |  |
space
Restful webservice calling syntax |  |  |
[POST] | /baseURL/ IAddress/GetPhones
[JSON input data] | pIAddress: | longValue, //interface address
[JSON result array] | { pbstrNumber: pbstrLocalCode: pbstrInternationalCode: pbstrExt: pbStatus: | "utf8StringValue", "utf8StringValue", "utf8StringValue", "utf8StringValue", booleanValue },
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
Calling argument description |  |  |
[out] BSTR | *pbstrNumber | The pure phone number part of the full telephone number. It is possible that the full telephone number is returned in this variable and the other parts of the telephone number left empty. |
[out] BSTR | *pbstrLocalCode | The local area code part of the telephone number. |
[out] BSTR | *pbstrInternationalCode | The international calling code part of the telephone number. |
[out] BSTR | *pbstrExt | the extension number part of the telephone number. |
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE the end of data is reached |
space |


  • IAddress
  • GetPostal

IAddress::GetPostal method |  |  | space
Retrieves the structured postal address part of the address |  |  |
space
Restful webservice calling syntax |  |  |
[POST] | /baseURL/ IAddress/GetPostal
[JSON input data] | pIAddress: | longValue, //interface address
[JSON result data] | pbstrStreet: pbstrPoBox: pbstrZip: pbstrCity: pbstrStateCode: pbstrCountryCode: pbStatus: | "utf8StringValue", "utf8StringValue", "utf8StringValue", "utf8StringValue", "utf8StringValue", "utf8StringValue", booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
C/C++ calling syntax |  |  |
HRESULT GetPostal( | BSTR BSTR BSTR BSTR BSTR BSTR VARIANT_BOOL | *pbstrStreet, *pbstrPoBox, *pbstrZip, *pbstrCity, *pbstrStateCode, *pbstrCountryCode, *pbStatus); |
[C/C++ return value] | S_OK | This value is returned if the function call was successful. |
 | S_FALSE | This value is returned if the end of an iteration is reached |
 | E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions. |
space
Calling argument description |  |  |
[out] BSTR | *pbstrStreet | The street name part of an address. |
[out] BSTR | *pbstrPoBox | The P.O. box code part of an address. Note that according to the Post the street and poBox parts should be used mutually exclusive. |
[out] BSTR | *pbstrZip | The ZIP code part of an address. |
[out] BSTR | *pbstrCity | The city name of an address. |
[out] BSTR | *pbstrStateCode | The optional state code part of an address. |
[out] BSTR | *pbstrCountryCode | The optional ISO country code part of an address. |
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE then an error occurred and GetAbortInfo should be called to retrieve the error string. |
space |


  • IAddress
  • Initialize

IAddress::Initialize method |  |  | space
Initializes all address variables. This method should be called before new data is supplied to reset all internally stored data. |  |  |
space
Restful webservice calling syntax |  |  |
[POST] | /baseURL/ IAddress/Initialize
[JSON input data] | pIAddress: | longValue, //interface address
[JSON result data] | pbStatus: | booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
C/C++ calling syntax |  |  |
HRESULT Initialize( | VARIANT_BOOL | *pbStatus); |
[C/C++ return value] | S_OK | This value is returned if the function call was successful. |
 | S_FALSE | This value is returned if the end of an iteration is reached |
 | E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions. |
space
Calling argument description |  |  |
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE then an error occurred and GetAbortInfo should be called to retrieve the error string. |
space |


  • IAddress
  • SetCompany

IAddress::SetCompany method |  |  | space
Sets the company's naming part of the address. Note that the subaddressing is part of the extended name and is always printed before any postal information. |  |  |
space
Restful webservice calling syntax |  |  |
[POST] | /baseURL/ IAddress/SetCompany
[JSON input data] | pIAddress: bstrCompanyName: bstrDepartment: bstrSubaddressing: | longValue, //interface address "utf8StringValue", "utf8StringValue", "utf8StringValue"
[JSON result data] | pbStatus: | booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
C/C++ calling syntax |  |  |
HRESULT SetCompany( | BSTR BSTR BSTR VARIANT_BOOL | bstrCompanyName, bstrDepartment, bstrSubaddressing, *pbStatus); |
[C/C++ return value] | S_OK | This value is returned if the function call was successful. |
 | S_FALSE | This value is returned if the end of an iteration is reached |
 | E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions. |
space
Calling argument description |  |  |
[in] BSTR | bstrCompanyName | The company's name. |
[in] BSTR | bstrDepartment | The optional department part of the company. |
[in] BSTR | bstrSubaddressing | The optional subaddressing information, e.g. a "c/o" like information as defined by the Post |
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE then an error occurred and GetAbortInfo should be called to retrieve the error string. |
space |


  • IAddress
  • SetFax

IAddress::SetFax method |  |  | space
Sets a structured fax number. The Swiss international calling code +41 is filtered in the printing. If the main software does not support structured pone numbers then all data is supplied in the bstrNumber variable. However, +41 is then no longer filtered. |  |  |
space
Restful webservice calling syntax |  |  |
[POST] | /baseURL/ IAddress/SetFax
[JSON input data] | pIAddress: bstrNumber: bstrLocalCode: bstrInternationalCode: bstrExt: | longValue, //interface address "utf8StringValue", "utf8StringValue", "utf8StringValue", "utf8StringValue"
[JSON result data] | pbStatus: | booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
C/C++ calling syntax |  |  |
HRESULT SetFax( | BSTR BSTR BSTR BSTR VARIANT_BOOL | bstrNumber, bstrLocalCode, bstrInternationalCode, bstrExt, *pbStatus); |
[C/C++ return value] | S_OK | This value is returned if the function call was successful. |
 | S_FALSE | This value is returned if the end of an iteration is reached |
 | E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions. |
space
Calling argument description |  |  |
[in] BSTR | bstrNumber | The pure fax number part of the fax number. It is possible to set the full fax number in this variable and leave the other parts of the fax number empty |
[in] BSTR | bstrLocalCode | The local area code part of the fax number. |
[in] BSTR | bstrInternationalCode | The international calling code part of the fax number. |
[in] BSTR | bstrExt | The extension number part of the fax number. |
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE then an error occurred and GetAbortInfo should be called to retrieve the error string. |
space |


  • IAddress
  • SetOnline

IAddress::SetOnline method |  |  | space
Sets the structured online part of the address. |  |  |
space
Restful webservice calling syntax |  |  |
[POST] | /baseURL/ IAddress/SetOnline
[JSON input data] | pIAddress: bstrEMail: bstrUrl: | longValue, //interface address "utf8StringValue", "utf8StringValue"
[JSON result data] | pbStatus: | booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
C/C++ calling syntax |  |  |
HRESULT SetOnline( | BSTR BSTR VARIANT_BOOL | bstrEMail, bstrUrl, *pbStatus); |
[C/C++ return value] | S_OK | This value is returned if the function call was successful. |
 | S_FALSE | This value is returned if the end of an iteration is reached |
 | E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions. |
space
Calling argument description |  |  |
[in] BSTR | bstrEMail | A relevant email address. |
[in] BSTR | bstrUrl | A relevant URL address. |
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE then an error occurred and GetAbortInfo should be called to retrieve the error string. |
space |


  • IAddress
  • SetPerson

IAddress::SetPerson method |  |  | space
Sets the person's naming part of the address. Note that the subaddressing is part of the extended name and is always printed before any postal information. |  |  |
space
Restful webservice calling syntax |  |  |
[POST] | /baseURL/ IAddress/SetPerson
[JSON input data] | pIAddress: bstrFamilyname: bstrGivenname: bstrSalutation: bstrTitle: bstrSubaddressing: | longValue, //interface address "utf8StringValue", "utf8StringValue", "utf8StringValue", "utf8StringValue", "utf8StringValue"
[JSON result data] | pbStatus: | booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
C/C++ calling syntax |  |  |
HRESULT SetPerson( | BSTR BSTR BSTR BSTR BSTR VARIANT_BOOL | bstrFamilyname, bstrGivenname, bstrSalutation, bstrTitle, bstrSubaddressing, *pbStatus); |
[C/C++ return value] | S_OK | This value is returned if the function call was successful. |
 | S_FALSE | This value is returned if the end of an iteration is reached |
 | E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions. |
space
Calling argument description |  |  |
[in] BSTR | bstrFamilyname | The family name (or last name) of the person. |
[in] BSTR | bstrGivenname | The given name (or first name) of the person. |
[in] BSTR | bstrSalutation | The optional salutation of the person. |
[in] BSTR | bstrTitle | The optional title of the person. |
[in] BSTR | bstrSubaddressing | The optional subaddressing information, e.g. a "c/o" like information as defined by the Post |
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE then an error occurred and GetAbortInfo should be called to retrieve the error string. |
space |


  • IAddress
  • SetPostal

IAddress::SetPostal method |  |  | space
Sets the structured postal address part. The Swiss ISO county code is the default but is filtered in the printing. |  |  |
space
Restful webservice calling syntax |  |  |
[POST] | /baseURL/ IAddress/SetPostal
[JSON input data] | pIAddress: bstrStreet: bstrPoBox: bstrZip: bstrCity: bstrStateCode: bstrCountryCode: | longValue, //interface address "utf8StringValue", "utf8StringValue", "utf8StringValue", "utf8StringValue", "utf8StringValue", "utf8StringValue"
[JSON result data] | pbStatus: | booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
C/C++ calling syntax |  |  |
HRESULT SetPostal( | BSTR BSTR BSTR BSTR BSTR BSTR VARIANT_BOOL | bstrStreet, bstrPoBox, bstrZip, bstrCity, bstrStateCode, bstrCountryCode, *pbStatus); |
[C/C++ return value] | S_OK | This value is returned if the function call was successful. |
 | S_FALSE | This value is returned if the end of an iteration is reached |
 | E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions. |
space
Calling argument description |  |  |
[in] BSTR | bstrStreet | The street name part of an address. |
[in] BSTR | bstrPoBox | The P.O. box code part of an address. Note that according to the Post the street and poBox parts should be used mutually exclusive. |
[in] BSTR | bstrZip | The mandatory ZIP code part of an address. |
[in] BSTR | bstrCity | The mandatory city name of an address. |
[in] BSTR | bstrStateCode | The optional state code part of an address. |
[in] BSTR | bstrCountryCode | The ISO country code of an address. |
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE then an error occurred and GetAbortInfo should be called to retrieve the error string. |
space |


  • IAddress
  • DestructAddress

IAddress::DestructAddress property |  |  | space
This property has a Restful Webservice representation only! Destructs/invalidates this IAddress interface instance. The counterpart property to generate an IAddress interface instance is IGeneralNotificationRequest::GetCreateAddress. |  |  |
space
Restful webservice calling syntax |  |  |
[PUT] | /baseURL/ IAddress/PutDestructAddress
[JSON input data] | pIAddress: | longValue, //interface address
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
Remarks |  |  |
This property has a Restful Webservice representation only! |  |  |
space |


  • IAddress
  • Type

IAddress::Type property | space
GetType returns the type of address either enAddressPerson or enAddressCompany if an address is defined at all.

If no address is defined then enAddressUndefined is returned.

space
Restful webservice calling syntax
[GET] | /baseURL/ IAddress/GetType?param
[param] pIAddress= longValue
[JSON result data] peType: longValue
[HTTP result status] | 200 | Return status 200 signals a successful method call
204 | Return status 204 (noContent) signals that the end of an iteration is reached
>= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do.
space
C/C++ calling syntax
[get] HRESULT | Type( AddressType *peType );
[C/C++ return value] | S_OK | This value is returned if the function call was successful.
S_FALSE | This value is returned if the end of an iteration is reached
E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions.
space
Calling argument description
[out,retval] AddressType | *peType
space
Remarks
If SmartPointers are used than the function names and calls are rewritten by Microsoft into the form
  • AddressType *GetType(void);
space


  • IGeneralNotificationManager

IGeneralNotificationManager interface | V4.51/28 Sep 2018
The IGeneralNotificationManager interface provides all necessary methods to produce a new message thread or reply to a received one.
  • To produce a new message thread first an instance of the IGeneralNotificationRequest interface is created by the GetGeneralNotificationRequest property. All data and parameters can be set by the supplied interface methods like SetPatient, SetSender,...
  • To reply to a received notification infoset basically the IGeneralNotificationRequest::SetReply method of the returned instance of the IGeneralNotificationRequest interface is used.
After all information is defined the notification XML infoset is produced optionally with signature and/or encryption using the GetXML method and the such generated XML file is thereafter transported electronically to the recipient. 		space
space
Methods | 9 methods
GetAbortInfo | Gets the abort information string with the error coded in the module language
GetLogSettings | Gets the current log settings for the module.
GetXML | The GetXML method generates the XML infoset based either on the data of a new notification using the IGeneralNotificationRequest interface or based on the received and replied XML infoset
GetXMLInfo | Preloads and analyzes a XML infoset regarding the accepted schema versions and other important information like the encryption status
LoadXML | Loads a received XML infoset back into memory for further processing via the returned interface instances
Print | The Print method is a visualization aid to preview/print the currently loaded data on screen or onto the local printer
PrintAdjust | Shows the print object adjustment dialog that allows to move print objects of a .vps report generator file
PrintSetup | Shows the printer setup dialog that allows to define the printer and its settings
SetLogSettings | Sets the log setting preferences for the module
space
Properties | 9 properties
[get] CreateGeneralNotificationManager | Creates an instance of the main IGeneralNotificationManager interface
[put] DestructGeneralNotificationManager | Destructs/invalidates a main instance of the IGeneralNotificationManager interface
[put] DestructGeneralNotificationRequest | Destructs/invalidates this IGeneralNotificationRequest interface instance
[put] DestructGeneralNotificationResponse | Destructs/invalidates this IGeneralNotificationResponse interface instance.
[get] GeneralNotificationRequest | The GetGeneralNotificationRequest property generates an instance of the IGeneralNotificationRequest interface
[get/put] ModuleLanguage | Gets/Sets the language for the module i.e
[get] ModuleVersion | Get the version of the GeneralNotificationManager module.
[get] ModuleVersionText | Gets the version of the GeneralNotificationManager module in textual form.
[get/put] Modus | Gets/Sets the operation modus of the module
space


  • IGeneralNotificationManager
  • GetAbortInfo

IGeneralNotificationManager::GetAbortInfo method |  |  | space
Gets the abort information string with the error coded in the module language. Call this method whenever the returned pbStatus variable of the primarily called method is VARIANT_FALSE and this primarily called method is not an iterator (GetFirst/GetNext methods). In the later case VARIANT_FALSE signals the end of data. |  |  |
space
Restful webservice calling syntax |  |  |
[POST] | /baseURL/ IGeneralNotificationManager/GetAbortInfo
[JSON input data] | pIGeneralNotificationManager: | longValue, //interface address
[JSON result data] | pbstrAbort: pbStatus: | "utf8StringValue", booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
C/C++ calling syntax |  |  |
HRESULT GetAbortInfo( | BSTR VARIANT_BOOL | *pbstrAbort, *pbStatus); |
[C/C++ return value] | S_OK | This value is returned if the function call was successful. |
 | S_FALSE | This value is returned if the end of an iteration is reached |
 | E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions. |
space
Calling argument description |  |  |
[out] BSTR | *pbstrAbort | Abort information string coded in the module language. |
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE then an error-in-error situation occurred. |
space |


  • IGeneralNotificationManager
  • GetLogSettings

IGeneralNotificationManager::GetLogSettings method | space
Gets the current log settings for the module.
space
Restful webservice calling syntax
[POST] | /baseURL/ IGeneralNotificationManager/GetLogSettings
[JSON input data] pIGeneralNotificationManager: longValue, //interface address
[JSON result data] plLogLevel:
plMaxSizeKB:
peDoArchive:
pbstrArchiveDir:
pbStatus: 		longValue,
longValue,
longValue,
"utf8StringValue",
booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call
204 | Return status 204 (noContent) signals that the end of an iteration is reached
>= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do.
space
C/C++ calling syntax
HRESULT GetLogSettings( long
long
YesNoType
BSTR
VARIANT_BOOL 		*plLogLevel,
*plMaxSizeKB,
*peDoArchive,
*pbstrArchiveDir,
*pbStatus);
[C/C++ return value] | S_OK | This value is returned if the function call was successful.
S_FALSE | This value is returned if the end of an iteration is reached
E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions.
space
Calling argument description
[out] long *plLogLevel The log activity level where
lLogLevel = 0 | Logging is turned off
lLogLevel = 1 | Normal log activity
lLogLevel > 1 | Debug log activity. Use this level only for debugging purposes
[out] long | *plMaxSizeKB | The maximum size in KB of the log file.
[out] YesNoType | *peDoArchive | eDoArchive defines if the log file is recycled if the maximum size is reached (enNo) or if the log file is archived (enYes).
[out] BSTR | *pbstrArchiveDir | The base directory where log files are archived. bstrArchiveDir is only defined if eDoArchive=enYes otherwise bstrArchiveDir is empty.
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE then an error occurred and GetAbortInfo should be called to retrieve the error string.
space


  • IGeneralNotificationManager
  • GetXML

IGeneralNotificationManager::GetXML method | space
The GetXML method generates the XML infoset based either on the data of a new notification using the IGeneralNotificationRequest interface or based on the received and replied XML infoset. In both cases the generation attributes are applied to the infoset generation, the XML is then validated against the XSD schema, and finally stored as UTF8 file in the internal working directory. The full file name to this XML document is returned in the pbstrOutputFile output variable.

The XML file must be saved to a different location as all temporary XML files in the working directory are deleted before the COM module shuts down!

Note about compatibility: the COM module is natively capable of producing the predecessor standard generalNotification440 by using the lGenerationAttributes=enGenerateDowngradeToV440. This option should be used as long as not all communication partners do understand the generalNotification450 standard.

Note about encryption: an encrypted XML infoset can not be loaded successfully by LoadXML. Therefore, to build a local archive besides encrypted XML infoset call GetXML twice once with the lGenerationAttributes = enGenerateXMLWithoutDocuments.

space
Restful webservice calling syntax
[POST] | /baseURL/ IGeneralNotificationManager/GetXML
[JSON input data] pIGeneralNotificationManager:
lGenerationAttributes:
plTimestamp: 		longValue, //interface address
longValue,
longValue
[JSON result data] pbstrOutputFile:
plValidationError:
plTimestamp:
pbstrUsedSchema:
pIGeneralNotificationResponse:
pbStatus: 		"utf8StringValue",
longValue,
"utf8StringValue",
longValue,
booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call
204 | Return status 204 (noContent) signals that the end of an iteration is reached
>= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do.
space
C/C++ calling syntax
HRESULT GetXML( long
BSTR
long
long
BSTR
IGeneralNotificationResponse
VARIANT_BOOL 		lGenerationAttributes,
*pbstrOutputFile,
*plValidationError,
*plTimestamp,
*pbstrUsedSchema,
**pIGeneralNotificationResponse,
*pbStatus);
[C/C++ return value] | S_OK | This value is returned if the function call was successful.
S_FALSE | This value is returned if the end of an iteration is reached
E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions.
space
Calling argument description
[in] long lGenerationAttributes This variable overrules the default behavior of the XML generation process even if the appropriate data have been defined.

lGenerationAttributes is a 32-bit integer where the possible "excludes" are values from the generationAttributes data type ORed together to form the overall command.

This feature is necessary to generate different "flavors" of XML infosets without re-setting input data. For instance, an encrypted XML infoset for the "to" entity can be produced and in a second call the XML infoset without encryption (lGenerationAttributes = enGenerateXMLWithoutEncryption) is requested for a local archive (that can be loaded back later!).

[out] BSTR *pbstrOutputFile The full file name (path + name) where the XML infoset is stored in UTF-8 mode.

The XML file must be saved to a different location as all temporary XML files in the working directory are deleted before the COM module shuts down!

In Restful Webservice output: pbstrOutputFile is a releative URL which must be downloaded in a subsequent GET process.

[out] long | *plValidationError | lValidationError is filled with the validation error code returned by the MSXML DOM parser. A zero value indicates that the validation was successful.
[in,out] long *plTimestamp The timestamp of the XML document as epoch time (seconds elapsed since 1.1.1970) that is used as timestamp of the notification object reference from that point on.

In a reply situation the "old" timestamp of the received XML infoset is returned.

[out] BSTR | *pbstrUsedSchema | The full name of the used XSD schema file.
[out] IGeneralNotificationResponse **pIGeneralNotificationResponse The instance of a IGeneralNotificationResponse interface allows to read back all currently loaded data.
The handle is NULL if an error occurred.
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE then an error occurred and GetAbortInfo should be called to retrieve the error string.
space


  • IGeneralNotificationManager
  • GetXMLInfo

IGeneralNotificationManager::GetXMLInfo method |  |  | space
Preloads and analyzes a XML infoset regarding the accepted schema versions and other important information like the encryption status. The generalNotification450 COM module understands and processes the generalNotification450 XSD standard as well as both predecessors, namely generalNotification440 and generalNotification430. Infosets of another XSD standard will return an error. This method should be called before calling LoadXML since the infoset is possibly encrypted. In this situation the corresponding PFX certificate and password must be supplied in the LoadXML method. |  |  |
space
Restful webservice calling syntax |  |  |
[POST] | /baseURL/ IGeneralNotificationManager/GetXMLInfo
[JSON input data] | pIGeneralNotificationManager: bstrInputFile: | longValue, //interface address "utf8StringValue"
[JSON result data] | pbstrUsedSchema: pbstrFromEAN: pbstrToEAN: peIsEncrypted: pbStatus: | "utf8StringValue", "utf8StringValue", "utf8StringValue", longValue, booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
C/C++ calling syntax |  |  |
HRESULT GetXMLInfo( | BSTR BSTR BSTR BSTR YesNoType VARIANT_BOOL | bstrInputFile, *pbstrUsedSchema, *pbstrFromEAN, *pbstrToEAN, *peIsEncrypted, *pbStatus); |
[C/C++ return value] | S_OK | This value is returned if the function call was successful. |
 | S_FALSE | This value is returned if the end of an iteration is reached |
 | E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions. |
space
Calling argument description |  |  |
[in] BSTR | bstrInputFile | The full file name (path + name) of a XML infoset. |
[out] BSTR | *pbstrUsedSchema | The full name of the used XSD schema file. |
[out] BSTR | *pbstrFromEAN | The transport EAN number of the sender as supplied by Stiftung Refdata |
[out] BSTR | *pbstrToEAN | The transport EAN number of the receiver as supplied by Stiftung Refdata |
[out] YesNoType | *peIsEncrypted | A Boolean that defines if the XML infoset is encrypted. If true the private PFX certificate/password of the "to" entity must be given in the LoadXML method otherwise the infoset can not be decrypted. |
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE then an error occurred and GetAbortInfo should be called to retrieve the error string. |
space |


  • IGeneralNotificationManager
  • LoadXML

IGeneralNotificationManager::LoadXML method |  |  | space
Loads a received XML infoset back into memory for further processing via the returned interface instances. The generalNotification450 COM module understands and processes the generalNotification450 XSD standard as well as both predecessors, namely generalNotification440 and generalNotification430. To analyze and retrieve the received data use the returned instance of the IGeneralNotificationResponse interface and/or preview/print the data. To generate a reply call the IGeneralNotificationRequest::SetReply method followed by the GetXML method. The latter one generates the new XML infoset ready to send back. |  |  |
space
Restful webservice calling syntax |  |  |
[POST] | /baseURL/ IGeneralNotificationManager/LoadXML?param
[param] | pIGeneralNotificationManager=longValue& bstrInputFile=urlEncodedString& bstrToPFXFile=urlEncodedString& bstrToPFXPassword=urlEncodedString + <application/octet-stream> input_file_upload_stream
[JSON result data] | pIGeneralNotificationRequest: pIGeneralNotificationResponse: pbStatus: | longValue, longValue, booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
C/C++ calling syntax |  |  |
HRESULT LoadXML( | BSTR BSTR BSTR IGeneralNotificationRequest IGeneralNotificationResponse VARIANT_BOOL | bstrInputFile, bstrToPFXFile, bstrToPFXPassword, **pIGeneralNotificationRequest, **pIGeneralNotificationResponse, *pbStatus); |
[C/C++ return value] | S_OK | This value is returned if the function call was successful. |
 | S_FALSE | This value is returned if the end of an iteration is reached |
 | E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions. |
space
Calling argument description |  |  |
[in] BSTR | bstrInputFile | The full file name (path + name) of a XML infoset. |
[in] BSTR | bstrToPFXFile | The file name of the PFX certificate that is the private certificate of the "toEAN" entity. This variable is not used if the XML infoset is not encrypted. |
[in] BSTR | bstrToPFXPassword | The password to open the PFX certificate. This variable is not used if the XML infoset is not encrypted. |
[out] IGeneralNotificationRequest | **pIGeneralNotificationRequest | The instance of a IGeneralNotificationRequest interface allows to define/override data. This instance given here is in the first place needed the make a reply. The handle is NULL if an error occurred. |
[out] IGeneralNotificationResponse | **pIGeneralNotificationResponse | The instance of a IGeneralNotificationResponse interface allows to read back all currently loaded data. The handle is NULL if an error occurred. |
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE then an error occurred and GetAbortInfo should be called to retrieve the error string. |
space |


  • IGeneralNotificationManager
  • Print

IGeneralNotificationManager::Print method | space
The Print method is a visualization aid to preview/print the currently loaded data on screen or onto the local printer. However, the generalNotification paradigm in its core is an electronic message exchange system. Thus, at the very end an XML infoset must be generated and sent to the recipient.

The bstrPrintTemplate variable obeys a special syntax and can be used to set special print commands like producing PDFs or changing print objects dynamically.

  • "How to generate PDF archive file" is a description about PDF archive files
  • "Syntax of the printTemplate variable"

Note: the usage of the SetReply method defines a singularity in the data space and the semantic interpretation of the data. As a consequence the print output differs before and after IGeneralNotificationRequest::SetReply!

IMPORTANT LICENSE NOTE The report engine used is Hexatech's ViewPro (www.hexatech.com). If you supply your own template files then you must have your own ViewPro license. By using this COM module you implicitly agree upon this restriction!

space
Restful webservice calling syntax
[POST] | /baseURL/ IGeneralNotificationManager/Print
[JSON input data] pIGeneralNotificationManager:
bstrPrintTemplate:
lGenerationAttributes:
ePrintPreview: 		longValue, //interface address
"utf8StringValue",
longValue,
longValue
[JSON result data] pbstrPDFFile:
pbStatus: 		"utf8StringValue",
booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call
204 | Return status 204 (noContent) signals that the end of an iteration is reached
>= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do.
space
C/C++ calling syntax
HRESULT Print( BSTR
long
YesNoType
VARIANT_BOOL 		bstrPrintTemplate,
lGenerationAttributes,
ePrintPreview,
*pbStatus);
[C/C++ return value] | S_OK | This value is returned if the function call was successful.
S_FALSE | This value is returned if the end of an iteration is reached
E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions.
space
Calling argument description
[in] BSTR bstrPrintTemplate The bstrPrintTemplate variable is used to explicitly change print template reports and/or print objects as defined in "Syntax of the printTemplate variable".

If bstrPrintTemplate is empty then the default print template of the defined data language ( IGeneralNotificationRequest:: Initialize method) is used.

[in] long lGenerationAttributes This variable overrules the default behavior of the print process.

lGenerationAttributes is a 32-bit integer where the possible "commands" are values from the generationAttributes data type ORed together to form the overall command.

[in] YesNoType ePrintPreview A Boolean that defines if print preview is used (enYes) or printing is done (enNo)

In Restful Webservice system: ePrintPreview is automatically set to enNo no matter what the input value is. Furthermore, printing is automatically redirected to a PDF output file since there are no printers available.

[out] BSTR *pbstrPDFFile In Restful webservice output:

pbstrPDFFile is a relative URL to a PDF file holding the result of the Print method. Therefore, after receiving the JSON result data do GET pbstrPDFile such as to have the produced printout.
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE then an error occurred and GetAbortInfo should be called to retrieve the error string.
space


  • IGeneralNotificationManager
  • PrintAdjust

IGeneralNotificationManager::PrintAdjust method | space
Shows the print object adjustment dialog that allows to move print objects of a .vps report generator file.

Besides the position adjustment of any available print object, there exists the possibility of move all print objects globally.

space
Restful webservice calling syntax
This method has no Restful Webservice representation!
space
C/C++ calling syntax
HRESULT PrintAdjust( BSTR
BSTR
VARIANT_BOOL 		bstrPrintTemplate,
bstrINIPath,
*pbStatus);
[C/C++ return value] | S_OK | This value is returned if the function call was successful.
S_FALSE | This value is returned if the end of an iteration is reached
E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions.
space
Calling argument description
[in] BSTR bstrPrintTemplate Either a full file name (path + name) or a logical name of a target .vps report generator file for which the settings will be defined.

There are predefined .vps files that can be accessed via one of the following case insensitive logical names:

Detail[_version]_language

where
  • version is one of {_450, _440}, the absence of a version identifier defaults to _450
  • language is one of {dt, fr, it}.
For example the logical name "Detail_fr" is the French print template of version 450.
[in] BSTR bstrINIPath Optional path to a directory where the .vpd printer setting file is stored. The name of the printer setting file is the same name as the .vps file but with a .vpd extension.

If bstrINIPath is left empty then the standard directory (the directory of the dll) is used.

[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE then an error occurred and GetAbortInfo should be called to retrieve the error string.
space


  • IGeneralNotificationManager
  • PrintSetup

IGeneralNotificationManager::PrintSetup method | space
Shows the printer setup dialog that allows to define the printer and its settings. When saving the data the selected print and the currently used computer is connected with the given .vps report generator file.
space
Restful webservice calling syntax
This method has no Restful Webservice representation!
space
C/C++ calling syntax
HRESULT PrintSetup( BSTR
BSTR
VARIANT_BOOL 		bstrPrintTemplate,
bstrINIPath,
*pbStatus);
[C/C++ return value] | S_OK | This value is returned if the function call was successful.
S_FALSE | This value is returned if the end of an iteration is reached
E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions.
space
Calling argument description
[in] BSTR bstrPrintTemplate Either a full file name (path + name) or a logical name of a target .vps report generator file for which the settings will be defined.

There are predefined .vps files that can be accessed via one of the following case insensitive logical names:

Detail[_version]_language

where
  • version is one of {_450, _440}, the absence of a version identifier defaults to _450
  • language is one of {dt, fr, it}.
For example the logical name "Detail_fr" is the French print template of version 450.
[in] BSTR bstrINIPath Optional path to a directory where the .vpd printer setting file is stored. The name of the printer setting file is the same name as the .vps file but with a .vpd extension.

If bstrINIPath is left empty then the standard directory (the directory of the dll) is used.

[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE then an error occurred and GetAbortInfo should be called to retrieve the error string.
space


  • IGeneralNotificationManager
  • SetLogSettings

IGeneralNotificationManager::SetLogSettings method | space
Sets the log setting preferences for the module.

The default for the log activity are: level=1, lMaxSizeKB=1000,eDoArchive=enNo,
and the log settings are persistent via the log file itself.

Note, that the log facility is a best effort system. If there is an error e.g. due to insufficient privileges to write the log entries then nothing is logged.

space
Restful webservice calling syntax
[POST] | /baseURL/ IGeneralNotificationManager/SetLogSettings
[JSON input data] pIGeneralNotificationManager:
lLogLevel:
lMaxSizeKB:
eDoArchive:
bstrArchiveDir: 		longValue, //interface address
longValue,
longValue,
longValue,
"utf8StringValue"
[JSON result data] pbStatus: booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call
204 | Return status 204 (noContent) signals that the end of an iteration is reached
>= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do.
space
C/C++ calling syntax
HRESULT SetLogSettings( long
long
YesNoType
BSTR
VARIANT_BOOL 		lLogLevel,
lMaxSizeKB,
eDoArchive,
bstrArchiveDir,
*pbStatus);
[C/C++ return value] | S_OK | This value is returned if the function call was successful.
S_FALSE | This value is returned if the end of an iteration is reached
E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions.
space
Calling argument description
[in] long lLogLevel The log activity level where
lLogLevel = 0 | Logging is turned off
lLogLevel = 1 | Normal log activity
lLogLevel > 1 | Debug log activity. Use this level only for debugging purposes

Any log level below 0 is corrected to 0.

[in] long lMaxSizeKB The maximum size in KB of the log file.
Any size below 1000 KB (= the default value) is corrected to the default value
[in] YesNoType | eDoArchive | eDoArchive defines if the log file is recycled once the maximum size is reached (enNo) or if the log file is archived (enYes) into the archive directory.
[in] BSTR bstrArchiveDir Defines the base directory where log files are archived. bstrArchiveDir is only used if eDoArchive=enYes. If bstrArchiveDir is empty and eDoArchive=enYes then the place of the module is used as the base archive directory.

If the base archive directory or directories below have insufficient privileges to create directories or write files archiving is not done!

[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE then an error occurred and GetAbortInfo should be called to retrieve the error string.
space


  • IGeneralNotificationManager
  • CreateGeneralNotificationManager

IGeneralNotificationManager::CreateGeneralNotificationManager property |  |  | space
This property has a Restful Webservice representation only! Creates an instance of the main IGeneralNotificationManager interface. To delete/invalidate this interface instance, the counterpart property PutDestructGeneralNotificationManager must be explicitly called, since the pIGeneralNotificationManager address has a global scope and is not automatically destructed. |  |  |
space
Restful webservice calling syntax |  |  |
[GET] | /baseURL/ IGeneralNotificationManager/GetCreateGeneralNotificationManager?param
[param] | pIGeneralNotificationManager= | longValue
[JSON result data] | pIGeneralNotificationManager: | longValue //interface address
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
Remarks |  |  |
This property has a Restful Webservice representation only! |  |  |
space |


  • IGeneralNotificationManager
  • DestructGeneralNotificationManager

IGeneralNotificationManager::DestructGeneralNotificationManager property |  |  | space
This property has a Restful Webservice representation only! Destructs/invalidates a main instance of the IGeneralNotificationManager interface. Please note, that all dependent, active interface instances generated with IGeneralNotificationManager::GetGeneralNotificationRequest, all dependent, active interface instances generated with IGeneralNotificationRequest::GetCreateAddress and all IGeneralNotificationResult interface instances under this main instance, are automatically destructed as well. The counterpart property to generate a main interface instance is IGeneralNotificationManager::GetCreateGeneralNotificationManager. |  |  |
space
Restful webservice calling syntax |  |  |
[PUT] | /baseURL/ IGeneralNotificationManager/PutDestructGeneralNotificationManager
[JSON input data] | pIGeneralNotificationManager: | longValue, //interface address
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
Remarks |  |  |
This property has a Restful Webservice representation only! |  |  |
space |


  • IGeneralNotificationManager
  • DestructGeneralNotificationRequest

IGeneralNotificationManager::DestructGeneralNotificationRequest property |  |  | space
This property has a Restful Webservice representation only! Destructs/invalidates this IGeneralNotificationRequest interface instance. The counterpart property to generate an IGeneralNotificationRequest interface instance is IGeneralNotificationRequestManager::GetGeneralNotificationRequest. |  |  |
space
Restful webservice calling syntax |  |  |
[PUT] | /baseURL/ IGeneralNotificationManager/PutDestructGeneralNotificationRequest
[JSON input data] | pIGeneralNotificationManager: pIGeneralNotificationRequest: | longValue, //interface address longValue, //interface address
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
Remarks |  |  |
This property has a Restful Webservice representation only! |  |  |
space |


  • IGeneralNotificationManager
  • DestructGeneralNotificationResponse

IGeneralNotificationManager::DestructGeneralNotificationResponse property |  |  | space
This property has a Restful Webservice representation only! Destructs/invalidates this IGeneralNotificationResponse interface instance. |  |  |
space
Restful webservice calling syntax |  |  |
[PUT] | /baseURL/ IGeneralNotificationManager/PutDestructGeneralNotificationResponse
[JSON input data] | pIGeneralNotificationManager: pIGeneralNotificationResponse: | longValue, //interface address longValue, //interface address
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
Remarks |  |  |
This property has a Restful Webservice representation only! |  |  |
space |


  • IGeneralNotificationManager
  • GeneralNotificationRequest

IGeneralNotificationManager::GeneralNotificationRequest property | space
The GetGeneralNotificationRequest property generates an instance of the IGeneralNotificationRequest interface.

This instance is needed to set the data of a new message thread or to reply to a received message.

space
Restful webservice calling syntax
[GET] | /baseURL/ IGeneralNotificationManager/GetGeneralNotificationRequest?param
[param] pIGeneralNotificationManager= longValue
[JSON result data] pIGeneralNotificationRequest: longValue //interface address
[HTTP result status] | 200 | Return status 200 signals a successful method call
204 | Return status 204 (noContent) signals that the end of an iteration is reached
>= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do.
space
C/C++ calling syntax
[get] HRESULT | GeneralNotificationRequest( IGeneralNotificationRequest **peGeneralNotificationRequest );
[C/C++ return value] | S_OK | This value is returned if the function call was successful.
S_FALSE | This value is returned if the end of an iteration is reached
E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions.
space
Calling argument description
[out,retval] IGeneralNotificationRequest | **peGeneralNotificationRequest
space
Remarks
If SmartPointers are used than the function names and calls are rewritten by Microsoft into the form
  • IGeneralNotificationRequest **GetGeneralNotificationRequest(void);
space


  • IGeneralNotificationManager
  • ModuleLanguage

IGeneralNotificationManager::ModuleLanguage property | space
Gets/Sets the language for the module i.e. the language in which the error strings are coded.

Note, that the module language and the data language (given by IGeneralNotificationRequest::Initialize) are independent and can be different!

space
Restful webservice calling syntax
[GET] | /baseURL/ IGeneralNotificationManager/GetModuleLanguage?param
[param] pIGeneralNotificationManager= longValue
[JSON result data] peModuleLanguage: longValue
[PUT] | /baseURL/ IGeneralNotificationManager/PutModuleLanguage
[JSON input data] pIGeneralNotificationManager:
eModuleLanguage: 		longValue, //interface address
longValue
[HTTP result status] | 200 | Return status 200 signals a successful method call
204 | Return status 204 (noContent) signals that the end of an iteration is reached
>= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do.
space
C/C++ calling syntax
[get] HRESULT | ModuleLanguage( LanguageType *peModuleLanguage );
[put] HRESULT | ModuleLanguage( LanguageType eModuleLanguage );
[C/C++ return value] | S_OK | This value is returned if the function call was successful.
S_FALSE | This value is returned if the end of an iteration is reached
E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions.
space
Calling argument description
[out,retval] LanguageType | *peModuleLanguage
[in] LanguageType | eModuleLanguage
space
Remarks
If SmartPointers are used than the function names and calls are rewritten by Microsoft into the form
  • LanguageType *GetModuleLanguage(void);
  • void PutModuleLanguage( LanguageType lModuleLanguage);
space


  • IGeneralNotificationManager
  • ModuleVersion

IGeneralNotificationManager::ModuleVersion property | space
Get the version of the GeneralNotificationManager module.
space
Restful webservice calling syntax
[GET] | /baseURL/ IGeneralNotificationManager/GetModuleVersion?param
[param] pIGeneralNotificationManager= longValue
[JSON result data] pbstrModuleVersion: "utf8StringValue"
[HTTP result status] | 200 | Return status 200 signals a successful method call
204 | Return status 204 (noContent) signals that the end of an iteration is reached
>= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do.
space
C/C++ calling syntax
[get] HRESULT | ModuleVersion( BSTR *pbstrModuleVersion );
[C/C++ return value] | S_OK | This value is returned if the function call was successful.
S_FALSE | This value is returned if the end of an iteration is reached
E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions.
space
Calling argument description
[out,retval] BSTR | *pbstrModuleVersion
space
Remarks
If SmartPointers are used than the function names and calls are rewritten by Microsoft into the form
  • BSTR *GetModuleVersion(void);
space


  • IGeneralNotificationManager
  • ModuleVersionText

IGeneralNotificationManager::ModuleVersionText property | space
Gets the version of the GeneralNotificationManager module in textual form.
space
Restful webservice calling syntax
[GET] | /baseURL/ IGeneralNotificationManager/GetModuleVersionText?param
[param] pIGeneralNotificationManager= longValue
[JSON result data] pbstrModuleVersionText: "utf8StringValue"
[HTTP result status] | 200 | Return status 200 signals a successful method call
204 | Return status 204 (noContent) signals that the end of an iteration is reached
>= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do.
space
C/C++ calling syntax
[get] HRESULT | ModuleVersionText( BSTR *pbstrModuleVersionText );
[C/C++ return value] | S_OK | This value is returned if the function call was successful.
S_FALSE | This value is returned if the end of an iteration is reached
E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions.
space
Calling argument description
[out,retval] BSTR | *pbstrModuleVersionText
space
Remarks
If SmartPointers are used than the function names and calls are rewritten by Microsoft into the form
  • BSTR *GetModuleVersionText(void);
space


  • IGeneralNotificationManager
  • Modus

IGeneralNotificationManager::Modus property | space
Gets/Sets the operation modus of the module.

The default modus is enProduction whereas for developing/debugging purposes enTest can be set.

space
Restful webservice calling syntax
[GET] | /baseURL/ IGeneralNotificationManager/GetModus?param
[param] pIGeneralNotificationManager= longValue
[JSON result data] peModus: longValue
[PUT] | /baseURL/ IGeneralNotificationManager/PutModus
[JSON input data] pIGeneralNotificationManager:
eModus: 		longValue, //interface address
longValue
[HTTP result status] | 200 | Return status 200 signals a successful method call
204 | Return status 204 (noContent) signals that the end of an iteration is reached
>= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do.
space
C/C++ calling syntax
[get] HRESULT | Modus( ModusType *peModus );
[put] HRESULT | Modus( ModusType eModus );
[C/C++ return value] | S_OK | This value is returned if the function call was successful.
S_FALSE | This value is returned if the end of an iteration is reached
E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions.
space
Calling argument description
[out,retval] ModusType | *peModus
[in] ModusType | eModus
space
Remarks
If SmartPointers are used than the function names and calls are rewritten by Microsoft into the form
  • ModusType *GetModus(void);
  • void PutModus( ModusType lModus);
space


  • IGeneralNotificationRequest

IGeneralNotificationRequest interface |  | V4.51/28 Sep 2018
The IGeneralNotificationRequest interface is used whenever a new message thread is started or to formulate a reply to a prior loaded thread. All the data and parameters are set by the available methods of the interface like SetPatient, SetSender,... |  | space
space
Methods |  | 14 methods
AddDocument | Attaches a PDF, JPG or PNG document to the list of documents |
AddInstruction | Adds an automation instruction to the list of instructions |
Finalize | Finalizes and validates all data set so far in the GeneralNotificationRequest interface |
GetAbortInfo | Gets the abort information string with the error coded in the module language |
Initialize | Initializes all input data in the IGeneralNotificationRequest interface |
SetLaw | Sets the data about the applied law and its dependent information |
SetMessage | Sets the primary message parameters of a new message thread as opposed to the SetReply method used when replying to an existing message thread |
SetNotification | Sets the main notification object reference |
SetPatient | Sets the primary parameters and structured address of the patient if a patient is involved in the notification thread |
SetRecipient | Sets the various identifiers (EAN, ZSR,...) and the structured address of the recipient |
SetRefObject | Sets the optional depended object reference of type credit, invoice, reminder, MCD, or form for which this notification thread is actually started |
SetReply | The SetReply method allows making a reply to an already received and loaded notification |
SetSender | Sets the various identifiers (EAN, ZSR,...) and the structured address of the sender |
SetTransport | Sets the transport information that is the routing information going from a sender (from) over a chain of intermediates (via) to the receiver (to) |
space
Properties |  | 3 properties
[get] CreateAddress | Creates an instance of the IAddress interface |
[put] DestructAddress | Destructs/invalidates the IAddress interface instance |
[put] DestructGeneralNotificationRequest | Destructs/invalidates this IGeneralNotificationRequest interface instance |
space |


  • IGeneralNotificationRequest
  • AddDocument

IGeneralNotificationRequest::AddDocument method | space
Attaches a PDF, JPG or PNG document to the list of documents.

Internally, the document will be transformed to a BASE64 octet representation to safeguard the binary nature of the file.

space
Restful webservice calling syntax
[POST] | /baseURL/ IGeneralNotificationRequest/AddDocument?param
[param] pIGeneralNotificationRequest=longValue&
bstrFile=urlEncodedString&
bstrTitle=urlEncodedString&
bstrMimeType=urlEncodedString
+
<application/octet-stream> input_file_upload_stream
[JSON result data] pbStatus: booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call
204 | Return status 204 (noContent) signals that the end of an iteration is reached
>= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do.
space
C/C++ calling syntax
HRESULT AddDocument( BSTR
BSTR
BSTR
VARIANT_BOOL 		bstrFile,
bstrTitle,
bstrMimeType,
*pbStatus);
[C/C++ return value] | S_OK | This value is returned if the function call was successful.
S_FALSE | This value is returned if the end of an iteration is reached
E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions.
space
Calling argument description
[in] BSTR | bstrFile | bstrFile supplies the full file name (path + name) of the document. Be sure, that privileges allows to open and read the file since the content is internally BASE64 coded.
[in] BSTR | bstrTitle | bstrTitle is the document's title on the primary system and thus describes the document in terms of its semantic content.
[in] BSTR bstrMimeType The MIME type of the document. The MIME type enables applications to define the format and eventually read the file (cf. RFC 2046 standardizes and names the commonly used MIME types).

Since the underlying XSD schema restricts the type of files, the MIME type must>/b> be one of

  • application/pdf for PDF files, , and image/png
  • image/jpeg for JPG graphic files
  • image/png for PNG graphic files
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE then an error occurred and GetAbortInfo should be called to retrieve the error string.
space


  • IGeneralNotificationRequest
  • AddInstruction

IGeneralNotificationRequest::AddInstruction method |  |  | space
Adds an automation instruction to the list of instructions. The instruction is formatted as a token/value pair Note that these instructions are defined purely between sender and receiver regarding the semantic meaning. The infoset is just the transport container. Note although that even if the notification deals only with such instructions, a meaningful message is still required as forced by the underlying XSD schema. |  |  |
space
Restful webservice calling syntax |  |  |
[POST] | /baseURL/ IGeneralNotificationRequest/AddInstruction
[JSON input data] | pIGeneralNotificationRequest: lGroupNumber: bstrToken: bstrValue: | longValue, //interface address longValue, "utf8StringValue", "utf8StringValue"
[JSON result data] | pbStatus: | booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
C/C++ calling syntax |  |  |
HRESULT AddInstruction( | long BSTR BSTR VARIANT_BOOL | lGroupNumber, bstrToken, bstrValue, *pbStatus); |
[C/C++ return value] | S_OK | This value is returned if the function call was successful. |
 | S_FALSE | This value is returned if the end of an iteration is reached |
 | E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions. |
space
Calling argument description |  |  |
[in] long | lGroupNumber | The lGroupNumber allows to further group the instruction set by a group numbering scheme. |
[in] BSTR | bstrToken | The token part of the token/value formatted instruction |
[in] BSTR | bstrValue | The value part of a token/value formatted instruction |
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE then an error occurred and GetAbortInfo should be called to retrieve the error string. |
space |


  • IGeneralNotificationRequest
  • Finalize

IGeneralNotificationRequest::Finalize method |  |  | space
Finalizes and validates all data set so far in the GeneralNotificationRequest interface. This method is the counterpart to the Initialize method. This method should be called after all data have been set in the IGeneralNotificationRequest interface since higher-level validation rules can only be called at the end of input. Therefore, be prepared to get validation errors at that point. |  |  |
space
Restful webservice calling syntax |  |  |
[POST] | /baseURL/ IGeneralNotificationRequest/Finalize
[JSON input data] | pIGeneralNotificationRequest: | longValue, //interface address
[JSON result data] | pbStatus: | booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
C/C++ calling syntax |  |  |
HRESULT Finalize( | VARIANT_BOOL | *pbStatus); |
[C/C++ return value] | S_OK | This value is returned if the function call was successful. |
 | S_FALSE | This value is returned if the end of an iteration is reached |
 | E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions. |
space
Calling argument description |  |  |
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE then an error occurred and GetAbortInfo should be called to retrieve the error string. |
space |


  • IGeneralNotificationRequest
  • GetAbortInfo

IGeneralNotificationRequest::GetAbortInfo method |  |  | space
Gets the abort information string with the error coded in the module language. Call this method whenever the returned pbStatus variable of the primarily called method is VARIANT_FALSE and this primarily called method is not an iterator (GetFirst/GetNext methods). In the later case VARIANT_FALSE signals the end of data. |  |  |
space
Restful webservice calling syntax |  |  |
[POST] | /baseURL/ IGeneralNotificationRequest/GetAbortInfo
[JSON input data] | pIGeneralNotificationRequest: | longValue, //interface address
[JSON result data] | pbstrAbort: pbStatus: | "utf8StringValue", booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
C/C++ calling syntax |  |  |
HRESULT GetAbortInfo( | BSTR VARIANT_BOOL | *pbstrAbort, *pbStatus); |
[C/C++ return value] | S_OK | This value is returned if the function call was successful. |
 | S_FALSE | This value is returned if the end of an iteration is reached |
 | E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions. |
space
Calling argument description |  |  |
[out] BSTR | *pbstrAbort | Abort information string coded in the module language. |
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE then an error-in-error situation occurred. |
space |


  • IGeneralNotificationRequest
  • Initialize

IGeneralNotificationRequest::Initialize method |  |  | space
Initializes all input data in the IGeneralNotificationRequest interface. This method is the counterpart to the Finalize method. This method should be called before any input is set in the IGeneralNotificationRequest interface to reset all internally stored data. |  |  |
space
Restful webservice calling syntax |  |  |
[POST] | /baseURL/ IGeneralNotificationRequest/Initialize
[JSON input data] | pIGeneralNotificationRequest: eDataLanguage: eIsConfidential: | longValue, //interface address longValue, longValue
[JSON result data] | pbStatus: | booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
C/C++ calling syntax |  |  |
HRESULT Initialize( | LanguageType YesNoType VARIANT_BOOL | eDataLanguage, eIsConfidential, *pbStatus); |
[C/C++ return value] | S_OK | This value is returned if the function call was successful. |
 | S_FALSE | This value is returned if the end of an iteration is reached |
 | E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions. |
space
Calling argument description |  |  |
[in] LanguageType | eDataLanguage | Sets the language in which the data part is coded. It is exactly the language in which the response is formulated. Note, that the data language and the module language (given by IGeneralNotificationManager::SetModuleLanguage property) are independent and can be different! |
[in] YesNoType | eIsConfidential | A Boolean that defines if the notification thread is confidential. Note that the confidentiality status is defined at the moment of the initial XML infoset generation, thereafter it must be inherited into each new reply cycle. |
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE then an error occurred and GetAbortInfo should be called to retrieve the error string. |
space |


  • IGeneralNotificationRequest
  • SetLaw

IGeneralNotificationRequest::SetLaw method |  |  | space
Sets the data about the applied law and its dependent information |  |  |
space
Restful webservice calling syntax |  |  |
[POST] | /baseURL/ IGeneralNotificationRequest/SetLaw
[JSON input data] | pIGeneralNotificationRequest: eLawType: dCaseDate: bstrCaseID: bstrInsuredID: | longValue, //interface address longValue, variantDateValue | "stringISODateValue", "utf8StringValue", "utf8StringValue"
[JSON result data] | pbStatus: | booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
C/C++ calling syntax |  |  |
HRESULT SetLaw( | LawType DATE BSTR BSTR VARIANT_BOOL | eLawType, dCaseDate, bstrCaseID, bstrInsuredID, *pbStatus); |
[C/C++ return value] | S_OK | This value is returned if the function call was successful. |
 | S_FALSE | This value is returned if the end of an iteration is reached |
 | E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions. |
space
Calling argument description |  |  |
[in] LawType | eLawType | The type of law to set from the LawType enumeration set |
[in] DATE | dCaseDate | The case date of the insurance (e.g. date of accident in UVG) This date might be undefined for certain laws (e.g. KVG|VVG) and left empty in such a case |
[in] BSTR | bstrCaseID | The case ID of the insurance (e.g. accident number in UVG) This ID might undefined for certain laws (e.g. KVG|VVG) and left empty in such a case |
[in] BSTR | bstrInsuredID | The patient's ID at the insurance This ID might be undefined for certain laws and left empty in such a case |
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE then an error occurred and GetAbortInfo should be called to retrieve the error string. |
space |


  • IGeneralNotificationRequest
  • SetMessage

IGeneralNotificationRequest::SetMessage method |  |  | space
Sets the primary message parameters of a new message thread as opposed to the SetReply method used when replying to an existing message thread. Note that the PDF form OID mechanism is a signal for the receiver to start a form process. In the Sumex1 environment the form OID is one from the medforms.ch space. |  |  |
space
Restful webservice calling syntax |  |  |
[POST] | /baseURL/ IGeneralNotificationRequest/SetMessage
[JSON input data] | pIGeneralNotificationRequest: bstrMessage: bstrFormOID: | longValue, //interface address "utf8StringValue", "utf8StringValue"
[JSON result data] | pbStatus: | booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
C/C++ calling syntax |  |  |
HRESULT SetMessage( | BSTR BSTR VARIANT_BOOL | bstrMessage, bstrFormOID, *pbStatus); |
[C/C++ return value] | S_OK | This value is returned if the function call was successful. |
 | S_FALSE | This value is returned if the end of an iteration is reached |
 | E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions. |
space
Calling argument description |  |  |
[in] BSTR | bstrMessage | The required message. |
[in] BSTR | bstrFormOID | An optional form OID. The definition of such a form OID signals the receiver to start a form process using the given OID as form template and using the reference object and the sender, receiver data as additional input. The resulting XML infoset of type generalFormRequest_430 must then be transmitted to receiver (the mirrored sender of this XML infoset). |
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE then an error occurred and GetAbortInfo should be called to retrieve the error string. |
space |


  • IGeneralNotificationRequest
  • SetNotification

IGeneralNotificationRequest::SetNotification method |  |  | space
Sets the main notification object reference. The dependent object references form a object reference chain with the notification as topmost object reference. The page "object reference" provides an in-depth description of the concepts of "object reference", "object reference chain", and "topmost object reference". |  |  |
space
Restful webservice calling syntax |  |  |
[POST] | /baseURL/ IGeneralNotificationRequest/SetNotification
[JSON input data] | pIGeneralNotificationRequest: bstrNotificationID: dNotificationDate: lNotificationTimestamp: | longValue, //interface address "utf8StringValue", variantDateValue | "stringISODateValue", longValue
[JSON result data] | pbStatus: | booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
C/C++ calling syntax |  |  |
HRESULT SetNotification( | BSTR DATE long VARIANT_BOOL | bstrNotificationID, dNotificationDate, lNotificationTimestamp, *pbStatus); |
[C/C++ return value] | S_OK | This value is returned if the function call was successful. |
 | S_FALSE | This value is returned if the end of an iteration is reached |
 | E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions. |
space
Calling argument description |  |  |
[in] BSTR | bstrNotificationID | The notification ID is the main software's ID of the notification. This is one of 3 identifiers that constitute the notification object reference. |
[in] DATE | dNotificationDate | The notification date is the main software's date of the notification. This is one of 3 identifiers that constitute the notification object reference. |
[in] long | lNotificationTimestamp | This is a UNIX timestamp defined at the moment of the notification's infoset generation. Set this variable 0 to indicate the generation of a new notification object reference. The IGeneralNotificationManager::GetXML method will return the timestamp that must be used from that point on as 3rd parameter of the object reference. This is one of 3 identifiers that constitute the notification object reference. The timestamp will be generated once for a certain notification object reference and thereafter the timestamp is always referenced |
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE then an error occurred and GetAbortInfo should be called to retrieve the error string. |
space |


  • IGeneralNotificationRequest
  • SetPatient

IGeneralNotificationRequest::SetPatient method | space
Sets the primary parameters and structured address of the patient if a patient is involved in the notification thread. This is in principle true as soon as a dependent object reference is defined. In reverse this means that a dependent object reference must be defined as soon as a patient is defined.

The address is defined via an instance of the IAddress interface and the address data must be defined prior to call the SetPatient method.

space
Restful webservice calling syntax
[POST] | /baseURL/ IGeneralNotificationRequest/SetPatient
[JSON input data] pIGeneralNotificationRequest:
eSexType:
dBirthdate:
bstrSSN:
pIAddress: 		longValue, //interface address
longValue,
variantDateValue | "stringISODateValue",
"utf8StringValue",
longValue
[JSON result data] pbStatus: booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call
204 | Return status 204 (noContent) signals that the end of an iteration is reached
>= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do.
space
C/C++ calling syntax
HRESULT SetPatient( SexType
DATE
BSTR
IAddress
VARIANT_BOOL 		eSexType,
dBirthdate,
bstrSSN,
*pIAddress,
*pbStatus);
[C/C++ return value] | S_OK | This value is returned if the function call was successful.
S_FALSE | This value is returned if the end of an iteration is reached
E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions.
space
Calling argument description
[in] SexType | eSexType | The patient's gender.
[in] DATE | dBirthdate | The patient's birthdate.
[in] BSTR bstrSSN Defines the social security number (SSN) of the patient whereupon 3 distinguished types are allowed:
  • the old 11 digit Swiss SSN ("AHV-Nummer") as defined by Federal Social Insurance Office
  • the new 13 digit Swiss SSN ("SV-Nummer") beginning with 756 as defined by Federal Social Insurance Office
  • the new 4-10 digit SSN of Liechtenstein ("AHV-Nummer") as defined by Liechtensteinische AHV-IV-FAK
The SSN can be supplied in its printed (with dots) or electronic (only digits) form.
[in] IAddress | *pIAddress | The instance of a IAddress interface that holds the structured address parts.
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE then an error occurred and GetAbortInfo should be called to retrieve the error string.
space


  • IGeneralNotificationRequest
  • SetRecipient

IGeneralNotificationRequest::SetRecipient method |  |  | space
Sets the various identifiers (EAN, ZSR,...) and the structured address of the recipient. The address is defined via a IAddress interface pointer and the address data must be defined prior to call this method. |  |  |
space
Restful webservice calling syntax |  |  |
[POST] | /baseURL/ IGeneralNotificationRequest/SetRecipient
[JSON input data] | pIGeneralNotificationRequest: bstrEAN: bstrZSR: bstrSpecialty: pIAddress: | longValue, //interface address "utf8StringValue", "utf8StringValue", "utf8StringValue", longValue
[JSON result data] | pbStatus: | booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
C/C++ calling syntax |  |  |
HRESULT SetRecipient( | BSTR BSTR BSTR IAddress VARIANT_BOOL | bstrEAN, bstrZSR, bstrSpecialty, *pIAddress, *pbStatus); |
[C/C++ return value] | S_OK | This value is returned if the function call was successful. |
 | S_FALSE | This value is returned if the end of an iteration is reached |
 | E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions. |
space
Calling argument description |  |  |
[in] BSTR | bstrEAN | The EAN number of the recipient as supplied by Stiftung Refdata |
[in] BSTR | bstrZSR | The optional ZSR number of the recipient as supplied by Santesuisse |
[in] BSTR | bstrSpecialty | An optional specialty, i.e. FMH title of the recipient |
[in] IAddress | *pIAddress | The instance of a IAddress interface that holds the structured address parts. A NULL pointer is supplied if no address should be set. |
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE then an error occurred and GetAbortInfo should be called to retrieve the error string. |
space |


  • IGeneralNotificationRequest
  • SetRefObject

IGeneralNotificationRequest::SetRefObject method | space
Sets the optional depended object reference of type credit, invoice, reminder, MCD, or form for which this notification thread is actually started.

This reference object forms an object reference chain with the notification as topmost object reference. The page "object reference" provides an in-depth description of the concepts of "object reference", "object reference chain", and "topmost object reference".

Note that the dependent object reference as well as the patient data must stem from that dependent request infoset!

space
Restful webservice calling syntax
[POST] | /baseURL/ IGeneralNotificationRequest/SetRefObject
[JSON input data] pIGeneralNotificationRequest:
eRefObjectType:
bstrRequestID:
dRequestDate:
lRequestTimestamp: 		longValue, //interface address
longValue,
"utf8StringValue",
variantDateValue | "stringISODateValue",
longValue
[JSON result data] pbStatus: booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call
204 | Return status 204 (noContent) signals that the end of an iteration is reached
>= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do.
space
C/C++ calling syntax
HRESULT SetRefObject( ObjectType
BSTR
DATE
long
VARIANT_BOOL 		eRefObjectType,
bstrRequestID,
dRequestDate,
lRequestTimestamp,
*pbStatus);
[C/C++ return value] | S_OK | This value is returned if the function call was successful.
S_FALSE | This value is returned if the end of an iteration is reached
E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions.
space
Calling argument description
[in] ObjectType | eRefObjectType | The type of the depended object reference.
[in] BSTR bstrRequestID The request ID is the main software's identification of the dependent reference object.

This is one of 3 identifiers that constitute this object reference.

[in] DATE dRequestDate The request date is the main software's date of the dependent reference object.

This is one of 3 identifiers that constitute this object reference.

[in] long lRequestTimestamp This is a UNIX timestamp defined at the moment of the dependent reference object's infoset generation.

This is one of 3 identifiers that constitute this object reference.

[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE then an error occurred and GetAbortInfo should be called to retrieve the error string.
space


  • IGeneralNotificationRequest
  • SetReply

IGeneralNotificationRequest::SetReply method | space
The SetReply method allows making a reply to an already received and loaded notification.

Please note that the usage of the SetReply method defines a singularity in the data space. Before the call to SetReply all IGeneralNotificationResponse methods return the received data and its semantic whereas after the call to SetReply the addresses are mirrored and the message list is further added with the reply. Therefore all returned data of the IGeneralNotificationResponse methods reflects this behavior!

Note that the form OID mechanism is a signal for the receiver to start a form process. In the Sumex1 environment the form OID is one from the medforms.ch space.

space
Restful webservice calling syntax
[POST] | /baseURL/ IGeneralNotificationRequest/SetReply
[JSON input data] pIGeneralNotificationRequest:
bstrMessage:
bstrFormOID: 		longValue, //interface address
"utf8StringValue",
"utf8StringValue"
[JSON result data] pbStatus: booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call
204 | Return status 204 (noContent) signals that the end of an iteration is reached
>= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do.
space
C/C++ calling syntax
HRESULT SetReply( BSTR
BSTR
VARIANT_BOOL 		bstrMessage,
bstrFormOID,
*pbStatus);
[C/C++ return value] | S_OK | This value is returned if the function call was successful.
S_FALSE | This value is returned if the end of an iteration is reached
E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions.
space
Calling argument description
[in] BSTR | bstrMessage | The reply to the currently available message thread
[in] BSTR bstrFormOID An optional PDF form OID.

The definition of such a form OID signals the receiver to start a form process using the given OID as form template and using the reference object and the sender, receiver data as additional input. The resulting XML infoset must then be transmitted to receiver (the mirrored sender of this XML infoset).

[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE then an error occurred and GetAbortInfo should be called to retrieve the error string.
space


  • IGeneralNotificationRequest
  • SetSender

IGeneralNotificationRequest::SetSender method |  |  | space
Sets the various identifiers (EAN, ZSR,...) and the structured address of the sender. The address is defined via an instance of the IAddress interface and the address data must be defined prior to call this method. |  |  |
space
Restful webservice calling syntax |  |  |
[POST] | /baseURL/ IGeneralNotificationRequest/SetSender
[JSON input data] | pIGeneralNotificationRequest: bstrEAN: bstrZSR: bstrSpecialty: pIAddress: | longValue, //interface address "utf8StringValue", "utf8StringValue", "utf8StringValue", longValue
[JSON result data] | pbStatus: | booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
C/C++ calling syntax |  |  |
HRESULT SetSender( | BSTR BSTR BSTR IAddress VARIANT_BOOL | bstrEAN, bstrZSR, bstrSpecialty, *pIAddress, *pbStatus); |
[C/C++ return value] | S_OK | This value is returned if the function call was successful. |
 | S_FALSE | This value is returned if the end of an iteration is reached |
 | E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions. |
space
Calling argument description |  |  |
[in] BSTR | bstrEAN | The EAN number of the sender as supplied by Stiftung Refdata |
[in] BSTR | bstrZSR | The optional ZSR number of the sender as supplied by Santesuisse |
[in] BSTR | bstrSpecialty | An optional specialty, i.e. FMH title of the sender. |
[in] IAddress | *pIAddress | The instance of a IAddress interface that holds the structured address parts. A NULL pointer is supplied if no address should be set. |
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE then an error occurred and GetAbortInfo should be called to retrieve the error string. |
space |


  • IGeneralNotificationRequest
  • SetTransport

IGeneralNotificationRequest::SetTransport method | space
Sets the transport information that is the routing information going from a sender (from) over a chain of intermediates (via) to the receiver (to). All the involved parties are defined by GLN as defined by Stiftung Refdata.

Furthermore, this method allows to define the parameters needed for sign and/or encrypt the resulting XML infoset. Therefore, read the notes about signature and encryption to get familiar with these concepts.

Important new feature: the electronic reachability of a recipient for a certain version of generalNotification is kind of chicken and egg problem. To solve this connectivity problem, the webservice medSRS (medical Standard Routing Service) has been created. By using the RESTful webservice method queryRHS one can find out, how and whether a specific recipient can be reached electronically. Please refer to the website medSRS.ch for getting an introduction to the topic or detailed information about the functionality of the webservice.

Instead of inputting the bstrToEan GLN literal, the query call queryRHS(glnProvider,glnRecipient) is supplied instead - cf. description of bstrToEAN below. Furthermore, should the query result indicate an unreachability for version V451, a query check for version V450 is automatically launched to investigate on the lower version. If the downgraded version is supported, than everything is prepared internally such that the method IGeneralNotificationManager::GetXML generates a downgrade automatically and transparently.

The usage of the patch can generate a new error code 'ERROR_RECIPIENTRHS_NOTAVAILABLE' indicating that a given recipient is not reachable. It is the decision of the calling program whether the error 'ERROR_RECIPIENTRHS_NOTAVAILABLE' will be considered or not.

space
Restful webservice calling syntax
[POST] | /baseURL/ IGeneralNotificationRequest/SetTransport
[JSON input data] pIGeneralNotificationRequest:
bstrFromEAN:
bstrFromPFXFile:
bstrFromPFXPassword:
bstrViaEAN:
bstrToEAN:
bstrToBinDERFile: 		longValue, //interface address
"utf8StringValue",
"utf8StringValue",
"utf8StringValue",
"utf8StringValue",
"utf8StringValue",
"utf8StringValue"
[JSON result data] pbStatus: booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call
204 | Return status 204 (noContent) signals that the end of an iteration is reached
>= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do.
space
C/C++ calling syntax
HRESULT SetTransport( BSTR
BSTR
BSTR
BSTR
BSTR
BSTR
VARIANT_BOOL 		bstrFromEAN,
bstrFromPFXFile,
bstrFromPFXPassword,
bstrViaEAN,
bstrToEAN,
bstrToBinDERFile,
*pbStatus);
[C/C++ return value] | S_OK | This value is returned if the function call was successful.
S_FALSE | This value is returned if the end of an iteration is reached
E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions.
space
Calling argument description
[in] BSTR | bstrFromEAN | The GLN number of the sender as defined by Stiftung Refdata
[in] BSTR bstrFromPFXFile The file name of the PFX certificate that is the private certificate of the "from" entity.
If the variable is empty or NULL then no signature is applied otherwise a signature might be applied depending on the lXMLGenerationAttributes of the GetXML method.
[in] BSTR | bstrFromPFXPassword | The password to open the PFX certificate. The password is only used if a PFX certificate is supplied.
[in] BSTR bstrViaEAN The chain of intermediates supplied as '@'-separated list of the GLN of the involved parties e.g. 'gln1@gln2'.

Each GLN is defined by Stiftung Refdata

[in] BSTR bstrToEAN The GLN number of the recipient as defined by Stiftung Refdata

Patch for querying medSRS:
bstrToEAN = "queryRHS(glnProvider,glnRecipient);"

where:
  • queryRHS( ) is a literal command
  • glnProvider is the official GLN of the service with a required pattern of ^76[0-9]{11}.
    Please note that the official GLN of the service provider is needed here, which is not necessarily identical with the GLN of the sender == bstrFromEAN. The latter may be a GLN from the private sector (^2[0-9]{12}) - this is a small but crucial difference.
  • glnRecipient is the official GLN of the recipient with a required pattern of ^76[0-9]{11}.
    Please note that the official GLN of the sender is needed here, which is not necessarily identical with the GLN of the recipient == bstrToEAN. The latter may be a GLN from the private sector (^2[0-9]{12}) - this is a small but crucial difference.
Note, that the patch is neither case- nor whitespace-sensitive.

For example, given the input 'queryRHS(7601001302112, 7601003000078)' the medSRS system is queried whether
the recipient Suva (GLN=7601003000078) can be reached via the given intermediate (bstrViaEAN) with the
standard 'generalNotification451' for the provider TMR (GLN=7601001302112).

The result of the RESTful webservice call can return 3 possible result states:

  1. the recipient (Suva) is reachable: the correct GLN bstrToEAN is returned and error state S_OK is defined
  2. the call is faulty because the parameters have a wrong format or the used intermediate (bstrViaEAN) is unknown on medSRS or the call has caused some other technical problem. In this case bstrToEAN=bstrRecipient (7601003000078 in the example) is set and the error state S_OK is defined
  3. the recipient (Suva) is not reachable: if there is the possibility of a downgrade, the RESTful call is repeated for the next lower version or bstrToEAN=bstrRecipient (7601003000078 in the example) is set and the error state 'ERROR_RECIPIENTRHS_NOTAVAILABLE' is defined.
It is the decision of the calling program whether the error 'ERROR_RECIPIENTRHS_NOTAVAILABLE' will be considered or not.
[in] BSTR bstrToBinDERFile The file name of the binary DER certificate that is the public certificate of the "to" entity.
If the variable is empty or NULL then no encryption is applied otherwise encryption might be applied depending on the lXMLGenerationAttributes of the GetXML
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE then an error occurred and GetAbortInfo should be called to retrieve the error string.
space


  • IGeneralNotificationRequest
  • CreateAddress

IGeneralNotificationRequest::CreateAddress property | space
Creates an instance of the IAddress interface.

Any address data is specified or retrieved using properties and methods of this interface. The interface is reusable for any semantic type of address. Just call the IAddress:Initialize method before starting to input new address data.

space
Restful webservice calling syntax
[GET] | /baseURL/ IGeneralNotificationRequest/GetCreateAddress?param
[param] pIGeneralNotificationRequest= longValue
[JSON result data] pIAddress: longValue //interface address
[HTTP result status] | 200 | Return status 200 signals a successful method call
204 | Return status 204 (noContent) signals that the end of an iteration is reached
>= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do.
space
C/C++ calling syntax
[get] HRESULT | CreateAddress( IAddress **peCreateAddress );
[C/C++ return value] | S_OK | This value is returned if the function call was successful.
S_FALSE | This value is returned if the end of an iteration is reached
E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions.
space
Calling argument description
[out,retval] IAddress | **peCreateAddress
space
Remarks
If SmartPointers are used than the function names and calls are rewritten by Microsoft into the form
  • IAddress **GetCreateAddress(void);
space


  • IGeneralNotificationRequest
  • DestructAddress

IGeneralNotificationRequest::DestructAddress property |  |  | space
This property has a Restful Webservice representation only! Destructs/invalidates the IAddress interface instance. The counterpart property to generate an IAddress interface instance is IGeneralNotificationRequest::GetCreateAddress. |  |  |
space
Restful webservice calling syntax |  |  |
[PUT] | /baseURL/ IGeneralNotificationRequest/PutDestructAddress
[JSON input data] | pIGeneralNotificationRequest: pIAddress: | longValue, //interface address longValue, //interface address
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
Remarks |  |  |
This property has a Restful Webservice representation only! |  |  |
space |


  • IGeneralNotificationRequest
  • DestructGeneralNotificationRequest

IGeneralNotificationRequest::DestructGeneralNotificationRequest property |  |  | space
This property has a Restful Webservice representation only! Destructs/invalidates this IGeneralNotificationRequest interface instance. The counterpart property to generate an IGeneralNotificationRequest interface instance is IGeneralNotificationManager::GetGeneralNotificationRequest. |  |  |
space
Restful webservice calling syntax |  |  |
[PUT] | /baseURL/ IGeneralNotificationRequest/PutDestructGeneralNotificationRequest
[JSON input data] | pIGeneralNotificationRequest: | longValue, //interface address
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
Remarks |  |  |
This property has a Restful Webservice representation only! |  |  |
space |


  • IGeneralNotificationResponse

IGeneralNotificationResponse interface |  | V4.51/28 Sep 2018
The IGeneralNotificationResponse interface allows to read back all data that either have been set by the methods of the IGeneralInvoiceRequest interface or have been loaded by the IGeneralNotificationManager::LoadXML method. |  | space
space
Methods |  | 18 methods
GetAbortInfo | Gets the abort information string with the error coded in the module language |
GetDocuments | Method for collecting all document data covered by the IGeneralNotificationResponse interface and returned as JSON array |
GetFirstDocument | Retrieves the first document from the list of documents |
GetFirstInstruction | Retrieves the first instruction as token/value pair |
GetFirstMessage | Retrieves the first notification message |
GetInstructions | Method for collecting all instruction data covered by the IGeneralNotificationResponse interface and returned as JSON array |
GetLaw | Retrieves the data about the applied law and its dependent information |
GetMessages | Method for collecting all message data covered by the IGeneralNotificationResponse interface and returned as JSON array |
GetNextDocument | Retrieves the next document from the list of documents |
GetNextInstruction | Retrieves the next instruction as token/value pair |
GetNextMessage | Retrieves the next notification message |
GetNotification | Retrieves the main notification object reference parameters |
GetPatient | Retrieves the primary parameters (sex, birth date, SSN,...) and structured address of the patient |
GetRecipient | Retrieves the various identifiers (EAN, ZSR,...) and the structured address of the recipient |
GetRefObject | Retrieves the dependent object reference parameters if any was defined |
GetRequest | Retrieves some basic parameters like the data language or the confidentiality status of the notification. |
GetSender | Retrieves the various identifiers (EAN, ZSR,...) and the structured address of the sender |
GetTransport | Returns the transport information that is the routing information going from a sender (from) over at least one intermediate (via) to the receiver (to) |
space
Properties |  | 1 properties
[put] DestructGeneralNotificationResponse | Destructs/invalidates this IGeneralNotificationResponse interface instance. |
space |


  • IGeneralNotificationResponse
  • GetAbortInfo

IGeneralNotificationResponse::GetAbortInfo method |  |  | space
Gets the abort information string with the error coded in the module language. Call this method whenever the returned pbStatus variable of the primarily called method is VARIANT_FALSE and this primarily called method is not an iterator (GetFirst/GetNext methods). In the later case VARIANT_FALSE signals the end of data. |  |  |
space
Restful webservice calling syntax |  |  |
[POST] | /baseURL/ IGeneralNotificationResponse/GetAbortInfo
[JSON input data] | pIGeneralNotificationResponse: | longValue, //interface address
[JSON result data] | pbstrAbort: pbStatus: | "utf8StringValue", booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
C/C++ calling syntax |  |  |
HRESULT GetAbortInfo( | BSTR VARIANT_BOOL | *pbstrAbort, *pbStatus); |
[C/C++ return value] | S_OK | This value is returned if the function call was successful. |
 | S_FALSE | This value is returned if the end of an iteration is reached |
 | E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions. |
space
Calling argument description |  |  |
[out] BSTR | *pbstrAbort | Abort information string coded in the module language. |
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE then an error-in-error situation occurred. |
space |


  • IGeneralNotificationResponse
  • GetDocuments

IGeneralNotificationResponse::GetDocuments method | space
This method has a Restful Webservice representation only!
Method for collecting all document data covered by the IGeneralNotificationResponse interface and returned as JSON array.

Please note that IGeneralNotificationResponse::GetDocuments takes over the functionality of the iterator pair IGeneralNotificationResponse::GetFirstDocument / IGeneralNotificationResponse::GetNextDocument with a single call, making the latter superfluous.
space
Restful webservice calling syntax
[POST] | /baseURL/ IGeneralNotificationResponse/GetDocuments
[JSON input data] pIGeneralNotificationResponse: longValue, //interface address
[JSON result array] { pbstrFile:
pbstrTitle:
pbstrMimeType:
pbStatus: 		"utf8StringValue",
"utf8StringValue",
"utf8StringValue",
booleanValue
},
[HTTP result status] | 200 | Return status 200 signals a successful method call
204 | Return status 204 (noContent) signals that the end of an iteration is reached
>= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do.
space
Calling argument description
[out] BSTR *pbstrFile *pbstrFile supplies the full file name (path + name) of the document in a temporary working directory.
Be sure to copy away the file to a different location as all files in the working directory are deleted before the COM module shuts down!

In Restful Webservice output: pbstrFile is a relative URL that subsequently must be downloaded by a GET process.

[out] BSTR | *pbstrTitle | The title of the document on the primary system. It thus describes the document to a certain degree in terms of its semantic content.
[out] BSTR *pbstrMimeType The MIME type of the document.

Since the underlying XSD schema restricts the type of files, the MIME type must be one of

  • application/pdf for PDF files
  • image/jpeg for JPG graphic files
  • image/png for PNG graphic files
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE the end of data is reached
space


  • IGeneralNotificationResponse
  • GetFirstDocument

IGeneralNotificationResponse::GetFirstDocument method | space
Retrieves the first document from the list of documents.

VARIANT_FALSE is returned if the end of the document list is reached.

space
Restful webservice calling syntax
[POST] | /baseURL/ IGeneralNotificationResponse/GetFirstDocument
[JSON input data] pIGeneralNotificationResponse: longValue, //interface address
[JSON result data] pbstrFile:
pbstrTitle:
pbstrMimeType:
pbStatus: 		"utf8StringValue",
"utf8StringValue",
"utf8StringValue",
booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call
204 | Return status 204 (noContent) signals that the end of an iteration is reached
>= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do.
space
C/C++ calling syntax
HRESULT GetFirstDocument( BSTR
BSTR
BSTR
VARIANT_BOOL 		*pbstrFile,
*pbstrTitle,
*pbstrMimeType,
*pbStatus);
[C/C++ return value] | S_OK | This value is returned if the function call was successful.
S_FALSE | This value is returned if the end of an iteration is reached
E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions.
space
Calling argument description
[out] BSTR *pbstrFile *pbstrFile supplies the full file name (path + name) of the document in a temporary working directory.
Be sure to copy away the file to a different location as all files in the working directory are deleted before the COM module shuts down!

In Restful Webservice output: pbstrFile is a relative URL that subsequently must be downloaded by a GET process.

[out] BSTR | *pbstrTitle | The title of the document on the primary system. It thus describes the document to a certain degree in terms of its semantic content.
[out] BSTR *pbstrMimeType The MIME type of the document.

Since the underlying XSD schema restricts the type of files, the MIME type must be one of

  • application/pdf for PDF files
  • image/jpeg for JPG graphic files
  • image/png for PNG graphic files
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE the end of data is reached
space


  • IGeneralNotificationResponse
  • GetFirstInstruction

IGeneralNotificationResponse::GetFirstInstruction method |  |  | space
Retrieves the first instruction as token/value pair. VARIANT_FALSE is returned if the end of the instruction list is reached. Note that these instructions are defined purely between sender and receiver regarding the semantic meaning. The infoset is just the transport container. |  |  |
space
Restful webservice calling syntax |  |  |
[POST] | /baseURL/ IGeneralNotificationResponse/GetFirstInstruction
[JSON input data] | pIGeneralNotificationResponse: | longValue, //interface address
[JSON result data] | plGroupNumber: pbstrToken: pbstrValue: pbStatus: | longValue, "utf8StringValue", "utf8StringValue", booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
C/C++ calling syntax |  |  |
HRESULT GetFirstInstruction( | long BSTR BSTR VARIANT_BOOL | *plGroupNumber, *pbstrToken, *pbstrValue, *pbStatus); |
[C/C++ return value] | S_OK | This value is returned if the function call was successful. |
 | S_FALSE | This value is returned if the end of an iteration is reached |
 | E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions. |
space
Calling argument description |  |  |
[out] long | *plGroupNumber | The lGroupNumber allows to further group the instruction set by a group numbering scheme. Note that the instructions are returned in the same sequence as the input was done. Therefore, the grouping into equal instructions must be done outside the COM module. |
[out] BSTR | *pbstrToken | The token part of the token/value formatted instruction |
[out] BSTR | *pbstrValue | The value part of the token/value formatted instruction |
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE the end of data is reached |
space |


  • IGeneralNotificationResponse
  • GetFirstMessage

IGeneralNotificationResponse::GetFirstMessage method |  |  | space
Retrieves the first notification message. VARIANT_FALSE is returned if the end of the message list is reached. Note that the very first message is the most recent one, any following message is older by one message exchange hop. Therefore, the message iterator forms a serialized message historization. |  |  |
space
Restful webservice calling syntax |  |  |
[POST] | /baseURL/ IGeneralNotificationResponse/GetFirstMessage
[JSON input data] | pIGeneralNotificationResponse: | longValue, //interface address
[JSON result data] | pbstrMessage: pbstrFormOID: pdMessageDate: pbStatus: | "utf8StringValue", "utf8StringValue", "stringISODateValue", booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
C/C++ calling syntax |  |  |
HRESULT GetFirstMessage( | BSTR BSTR DATE VARIANT_BOOL | *pbstrMessage, *pbstrFormOID, *pdMessageDate, *pbStatus); |
[C/C++ return value] | S_OK | This value is returned if the function call was successful. |
 | S_FALSE | This value is returned if the end of an iteration is reached |
 | E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions. |
space
Calling argument description |  |  |
[out] BSTR | *pbstrMessage | The most recent message. |
[out] BSTR | *pbstrFormOID | An optional OID of a PDF form. If this form OID is set then this signals to start a form process using the GeneralFormRequestManager450 COM module and thereby generating a generalFormRequest_450.xsd based XML infoset. The sender, receiver, and reference object should be copied and the given form OID used as PDF template. |
[out] DATE | *pdMessageDate | The date when the most recent message was generated. |
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE the end of data is reached |
space |


  • IGeneralNotificationResponse
  • GetInstructions

IGeneralNotificationResponse::GetInstructions method |  |  | space
This method has a Restful Webservice representation only! Method for collecting all instruction data covered by the IGeneralNotificationResponse interface and returned as JSON array. Please note that IGeneralNotificationResponse::GetInstructions takes over the functionality of the iterator pair IGeneralNotificationResponse::GetFirstInstruction / IGeneralNotificationResponse::GetNextInstruction with a single call, making the latter superfluous. |  |  |
space
Restful webservice calling syntax |  |  |
[POST] | /baseURL/ IGeneralNotificationResponse/GetInstructions
[JSON input data] | pIGeneralNotificationResponse: | longValue, //interface address
[JSON result array] | { plGroupNumber: pbstrToken: pbstrValue: pbStatus: | longValue, "utf8StringValue", "utf8StringValue", booleanValue },
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
Calling argument description |  |  |
[out] long | *plGroupNumber | The lGroupNumber allows to further group the instruction set by a group numbering scheme. Note that the instructions are returned in the same sequence as the input was done. Therefore, the grouping into equal instructions must be done outside the COM module. |
[out] BSTR | *pbstrToken | The token part of the token/value formatted instruction |
[out] BSTR | *pbstrValue | The value part of the token/value formatted instruction |
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE the end of data is reached |
space |


  • IGeneralNotificationResponse
  • GetLaw

IGeneralNotificationResponse::GetLaw method |  |  | space
Retrieves the data about the applied law and its dependent information |  |  |
space
Restful webservice calling syntax |  |  |
[POST] | /baseURL/ IGeneralNotificationResponse/GetLaw
[JSON input data] | pIGeneralNotificationResponse: | longValue, //interface address
[JSON result data] | peLawType: pdCaseDate: pbstrCaseID: pbstrInsuredID: pbStatus: | longValue, "stringISODateValue", "utf8StringValue", "utf8StringValue", booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
C/C++ calling syntax |  |  |
HRESULT GetLaw( | LawType DATE BSTR BSTR VARIANT_BOOL | *peLawType, *pdCaseDate, *pbstrCaseID, *pbstrInsuredID, *pbStatus); |
[C/C++ return value] | S_OK | This value is returned if the function call was successful. |
 | S_FALSE | This value is returned if the end of an iteration is reached |
 | E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions. |
space
Calling argument description |  |  |
[out] LawType | *peLawType | Defines the type of law as given by the law type enumeration set. |
[out] DATE | *pdCaseDate | The case date of the insurance (e.g. date of accident in UVG) This date might be undefined for certain laws (e.g. KVG|VVG) and is left empty in such a case |
[out] BSTR | *pbstrCaseID | The case ID of the insurance (e.g. accident number in UVG) This caseID might be undefined for certain laws (e.g. KVG|VVG) and is left empty in such a case |
[out] BSTR | *pbstrInsuredID | The patient's ID at the insurance This patientID might be undefined for certain laws and is left empty in such a case |
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE then the law container was not set/defined. |
space |


  • IGeneralNotificationResponse
  • GetMessages

IGeneralNotificationResponse::GetMessages method |  |  | space
This method has a Restful Webservice representation only! Method for collecting all message data covered by the IGeneralNotificationResponse interface and returned as JSON array. Please note that IGeneralNotificationResponse::GetMessages takes over the functionality of the iterator pair IGeneralNotificationResponse::GetFirstMessage / IGeneralNotificationResponse::GetNextMessage with a single call, making the latter superfluous. |  |  |
space
Restful webservice calling syntax |  |  |
[POST] | /baseURL/ IGeneralNotificationResponse/GetMessages
[JSON input data] | pIGeneralNotificationResponse: | longValue, //interface address
[JSON result array] | { pbstrMessage: pbstrFormOID: pdMessageDate: pbStatus: | "utf8StringValue", "utf8StringValue", "stringISODateValue", booleanValue },
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
Calling argument description |  |  |
[out] BSTR | *pbstrMessage | The most recent message. |
[out] BSTR | *pbstrFormOID | An optional OID of a PDF form. If this form OID is set then this signals to start a form process using the GeneralFormRequestManager450 COM module and thereby generating a generalFormRequest_450.xsd based XML infoset. The sender, receiver, and reference object should be copied and the given form OID used as PDF template. |
[out] DATE | *pdMessageDate | The date when the most recent message was generated. |
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE the end of data is reached |
space |


  • IGeneralNotificationResponse
  • GetNextDocument

IGeneralNotificationResponse::GetNextDocument method | space
Retrieves the next document from the list of documents.

VARIANT_FALSE is returned if the end of the document list is reached.

space
Restful webservice calling syntax
[POST] | /baseURL/ IGeneralNotificationResponse/GetNextDocument
[JSON input data] pIGeneralNotificationResponse: longValue, //interface address
[JSON result data] pbstrFile:
pbstrTitle:
pbstrMimeType:
pbStatus: 		"utf8StringValue",
"utf8StringValue",
"utf8StringValue",
booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call
204 | Return status 204 (noContent) signals that the end of an iteration is reached
>= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do.
space
C/C++ calling syntax
HRESULT GetNextDocument( BSTR
BSTR
BSTR
VARIANT_BOOL 		*pbstrFile,
*pbstrTitle,
*pbstrMimeType,
*pbStatus);
[C/C++ return value] | S_OK | This value is returned if the function call was successful.
S_FALSE | This value is returned if the end of an iteration is reached
E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions.
space
Calling argument description
[out] BSTR *pbstrFile *pbstrFile supplies the full file name (path + name) of the document in a temporary working directory.
Be sure to copy away the file to a different location as all files in the working directory are deleted before the COM module shuts down!

In Restful Webservice output: pbstrFile is a relative URL that subsequently must be downloaded by a GET process.

[out] BSTR *pbstrTitle The title of the document on the primary system. It thus describes
the document to a certain degree in terms of its semantic content.
[out] BSTR *pbstrMimeType The MIME type of the document.

Since the underlying XSD schema restricts the type of files, the MIME type must be one of

  • application/pdf for PDF files
  • image/jpeg for JPG graphic files
  • image/png for PNG graphic files
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE the end of data is reached
space


  • IGeneralNotificationResponse
  • GetNextInstruction

IGeneralNotificationResponse::GetNextInstruction method |  |  | space
Retrieves the next instruction as token/value pair. VARIANT_FALSE is returned if the end of the instruction list is reached. Note that these instructions are defined purely between sender and receiver regarding the semantic meaning. The infoset is just the transport container. |  |  |
space
Restful webservice calling syntax |  |  |
[POST] | /baseURL/ IGeneralNotificationResponse/GetNextInstruction
[JSON input data] | pIGeneralNotificationResponse: | longValue, //interface address
[JSON result data] | plGroupNumber: pbstrToken: pbstrValue: pbStatus: | longValue, "utf8StringValue", "utf8StringValue", booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
C/C++ calling syntax |  |  |
HRESULT GetNextInstruction( | long BSTR BSTR VARIANT_BOOL | *plGroupNumber, *pbstrToken, *pbstrValue, *pbStatus); |
[C/C++ return value] | S_OK | This value is returned if the function call was successful. |
 | S_FALSE | This value is returned if the end of an iteration is reached |
 | E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions. |
space
Calling argument description |  |  |
[out] long | *plGroupNumber | The lGroupNumber allows to further group the instruction set by a group numbering scheme. Note that the instructions are returned in the same sequence as the input was done. Therefore, the grouping into equal instructions must be done outside the COM module. |
[out] BSTR | *pbstrToken | The token part of the token/value formatted instruction |
[out] BSTR | *pbstrValue | The value part of the token/value formatted instruction |
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE the end of data is reached |
space |


  • IGeneralNotificationResponse
  • GetNextMessage

IGeneralNotificationResponse::GetNextMessage method |  |  | space
Retrieves the next notification message. VARIANT_FALSE is returned if the end of the message list is reached. Note that the very first message is the most recent one, any following message is older by one message exchange hop. Therefore, the message iterator forms a serialized message historization. |  |  |
space
Restful webservice calling syntax |  |  |
[POST] | /baseURL/ IGeneralNotificationResponse/GetNextMessage
[JSON input data] | pIGeneralNotificationResponse: | longValue, //interface address
[JSON result data] | pbstrMessage: pbstrFormOID: pdMessageDate: pbStatus: | "utf8StringValue", "utf8StringValue", "stringISODateValue", booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
C/C++ calling syntax |  |  |
HRESULT GetNextMessage( | BSTR BSTR DATE VARIANT_BOOL | *pbstrMessage, *pbstrFormOID, *pdMessageDate, *pbStatus); |
[C/C++ return value] | S_OK | This value is returned if the function call was successful. |
 | S_FALSE | This value is returned if the end of an iteration is reached |
 | E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions. |
space
Calling argument description |  |  |
[out] BSTR | *pbstrMessage | The message on the current historization level. |
[out] BSTR | *pbstrFormOID | An optional OID of a form. This form OID must be ignored as it is just a historicized one. |
[out] DATE | *pdMessageDate | The date when the message was generated. |
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE the end of data is reached |
space |


  • IGeneralNotificationResponse
  • GetNotification

IGeneralNotificationResponse::GetNotification method |  |  | space
Retrieves the main notification object reference parameters. The dependent object references (if supplied in the request) form a object reference chain with this notification object as topmost object reference. The page "object reference" provides an in-depth description of the concepts of "object reference", "object reference chain", and "topmost object reference". |  |  |
space
Restful webservice calling syntax |  |  |
[POST] | /baseURL/ IGeneralNotificationResponse/GetNotification
[JSON input data] | pIGeneralNotificationResponse: | longValue, //interface address
[JSON result data] | pbstrNotificationID: pdNotificationDate: plNotificationTimestamp: pbStatus: | "utf8StringValue", "stringISODateValue", longValue, booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
C/C++ calling syntax |  |  |
HRESULT GetNotification( | BSTR DATE long VARIANT_BOOL | *pbstrNotificationID, *pdNotificationDate, *plNotificationTimestamp, *pbStatus); |
[C/C++ return value] | S_OK | This value is returned if the function call was successful. |
 | S_FALSE | This value is returned if the end of an iteration is reached |
 | E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions. |
space
Calling argument description |  |  |
[out] BSTR | *pbstrNotificationID | The notification ID is the main software's identification of the notification. This is one of 3 identifiers that form the notification object reference. |
[out] DATE | *pdNotificationDate | The notification date is the main software's date of the notification. This is one of 3 identifiers that form the notification object reference. |
[out] long | *plNotificationTimestamp | This is a UNIX timestamp defined at the moment of the notification's infoset generation. This is one of 3 identifiers that form the notification object reference. |
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE then an error occurred and GetAbortInfo should be called to retrieve the error string. |
space |


  • IGeneralNotificationResponse
  • GetPatient

IGeneralNotificationResponse::GetPatient method | space
Retrieves the primary parameters (sex, birth date, SSN,...) and structured address of the patient.

The address is defined via an IAddress interface pointer and the address data must be retrieved using the methods of IAddress.

space
Restful webservice calling syntax
[POST] | /baseURL/ IGeneralNotificationResponse/GetPatient
[JSON input data] pIGeneralNotificationResponse: longValue, //interface address
[JSON result data] peSexType:
pdBirthdate:
pbstrSSN:
pIAddress:

pbStatus: 		longValue,
"stringISODateValue",
"utf8StringValue",
{
pbIsPrivateAddress: true,
pbstrCompanyName: "utf8StringValue",
pbstrDepartment: "utf8StringValue",
pbstrSalutation: "utf8StringValue",
pbstrTitle: "utf8StringValue",
pbstrFamilyname: "utf8StringValue",
pbstrGivenname: "utf8StringValue",
pbstrSubaddressing: "utf8StringValue",
pbstrStreet: "utf8StringValue",
pbstrPoBox: "utf8StringValue",
pbstrZip: "utf8StringValue",
pbstrCity: "utf8StringValue",
pbstrStateCode: "utf8StringValue",
pbstrCountryCode: "utf8StringValue",
pbstrPhone1: "utf8StringValue",
pbstrPhone2: "utf8StringValue",
pbstrPhone3: "utf8StringValue",
pbstrFax: "utf8StringValue",
pbstrEMail: "utf8StringValue",
pbstrUrl: "utf8StringValue"
},
booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call
204 | Return status 204 (noContent) signals that the end of an iteration is reached
>= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do.
space
C/C++ calling syntax
HRESULT GetPatient( SexType
DATE
BSTR
IAddress
VARIANT_BOOL 		*peSexType,
*pdBirthdate,
*pbstrSSN,
**pIAddress,
*pbStatus);
[C/C++ return value] | S_OK | This value is returned if the function call was successful.
S_FALSE | This value is returned if the end of an iteration is reached
E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions.
space
Calling argument description
[out] SexType | *peSexType | The patient's gender.
[out] DATE | *pdBirthdate | The patient's birthdate.
[out] BSTR *pbstrSSN The social security number (SSN) of the patient in its printed form whereupon 3 distinguished types are possible:
  • the old 11 digit Swiss SSN ("AHV-Nummer") as defined by Federal Social Insurance Office
  • the new 13 digit Swiss SSN ("SV-Nummer") beginning with 756 as defined by Federal Social Insurance Office
  • the new 4-10 digit SSN of Liechtenstein ("AHV-Nummer") as defined by Liechtensteinische AHV-IV-FAK
[out] IAddress **pIAddress The instance of a IAddress interface that allows to read back the structured address data.
If no address is defined then the handle is NULL.
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE then the patient data is undefined.
space


  • IGeneralNotificationResponse
  • GetRecipient

IGeneralNotificationResponse::GetRecipient method |  |  | space
Retrieves the various identifiers (EAN, ZSR,...) and the structured address of the recipient. Note that the recipient address is mirrored and becomes the sender address after the singularity point that is after calling IGeneralNotificationRequest::SetReply. |  |  |
space
Restful webservice calling syntax |  |  |
[POST] | /baseURL/ IGeneralNotificationResponse/GetRecipient
[JSON input data] | pIGeneralNotificationResponse: | longValue, //interface address
[JSON result data] | pbstrEAN: pbstrZSR: pbstrSpecialty: pIAddress: pbStatus: | "utf8StringValue", "utf8StringValue", "utf8StringValue", { pbIsPrivateAddress: true, pbstrCompanyName: "utf8StringValue", pbstrDepartment: "utf8StringValue", pbstrSalutation: "utf8StringValue", pbstrTitle: "utf8StringValue", pbstrFamilyname: "utf8StringValue", pbstrGivenname: "utf8StringValue", pbstrSubaddressing: "utf8StringValue", pbstrStreet: "utf8StringValue", pbstrPoBox: "utf8StringValue", pbstrZip: "utf8StringValue", pbstrCity: "utf8StringValue", pbstrStateCode: "utf8StringValue", pbstrCountryCode: "utf8StringValue", pbstrPhone1: "utf8StringValue", pbstrPhone2: "utf8StringValue", pbstrPhone3: "utf8StringValue", pbstrFax: "utf8StringValue", pbstrEMail: "utf8StringValue", pbstrUrl: "utf8StringValue" }, booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
C/C++ calling syntax |  |  |
HRESULT GetRecipient( | BSTR BSTR BSTR IAddress VARIANT_BOOL | *pbstrEAN, *pbstrZSR, *pbstrSpecialty, **pIAddress, *pbStatus); |
[C/C++ return value] | S_OK | This value is returned if the function call was successful. |
 | S_FALSE | This value is returned if the end of an iteration is reached |
 | E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions. |
space
Calling argument description |  |  |
[out] BSTR | *pbstrEAN | The EAN number of the recipient as supplied by Stiftung Refdata |
[out] BSTR | *pbstrZSR | The optional ZSR number of the recipient as supplied by Santesuisse |
[out] BSTR | *pbstrSpecialty | The optional specialty, i.e. FMH title of the recipient. |
[out] IAddress | **pIAddress | The instance of a IAddress interface that allows to read back the structured address data. If no address is defined then the handle is NULL. |
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE then an error occurred and GetAbortInfo should be called to retrieve the error string. |
space |


  • IGeneralNotificationResponse
  • GetRefObject

IGeneralNotificationResponse::GetRefObject method |  |  | space
Retrieves the dependent object reference parameters if any was defined. The dependent object references (if supplied in the request) form a object reference chain with the notification as topmost object reference. The page "object reference" provides an in-depth description of the concepts of "object reference", "object reference chain", and "topmost object reference". |  |  |
space
Restful webservice calling syntax |  |  |
[POST] | /baseURL/ IGeneralNotificationResponse/GetRefObject
[JSON input data] | pIGeneralNotificationResponse: | longValue, //interface address
[JSON result data] | peRefObjectType: pbstrRequestID: pdRequestDate: plRequestTimestamp: pbStatus: | longValue, "utf8StringValue", "stringISODateValue", longValue, booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
C/C++ calling syntax |  |  |
HRESULT GetRefObject( | ObjectType BSTR DATE long VARIANT_BOOL | *peRefObjectType, *pbstrRequestID, *pdRequestDate, *plRequestTimestamp, *pbStatus); |
[C/C++ return value] | S_OK | This value is returned if the function call was successful. |
 | S_FALSE | This value is returned if the end of an iteration is reached |
 | E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions. |
space
Calling argument description |  |  |
[out] ObjectType | *peRefObjectType | The type of the depended object reference being one type of the enumeration list of reference object types. |
[out] BSTR | *pbstrRequestID | The request ID is the main software's identification of the reminder ("Mahnnummer"). This is one of 3 identifiers that form this object reference. |
[out] DATE | *pdRequestDate | The request date is the main software's date of the dependent reference object. This is one of 3 identifiers that form this object reference. |
[out] long | *plRequestTimestamp | This is a UNIX timestamp defined at the moment of the dependent reference object. This is one of 3 identifiers that form this object reference. |
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE then the referenced object data is undefined. |
space |


  • IGeneralNotificationResponse
  • GetRequest

IGeneralNotificationResponse::GetRequest method |  |  | space
Retrieves some basic parameters like the data language or the confidentiality status of the notification. |  |  |
space
Restful webservice calling syntax |  |  |
[POST] | /baseURL/ IGeneralNotificationResponse/GetRequest
[JSON input data] | pIGeneralNotificationResponse: | longValue, //interface address
[JSON result data] | peDataLanguage: peIsConfidential: peIsXMLLoaded: peIsReplyDataset: pbStatus: | longValue, longValue, longValue, longValue, booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
C/C++ calling syntax |  |  |
HRESULT GetRequest( | LanguageType YesNoType YesNoType YesNoType VARIANT_BOOL | *peDataLanguage, *peIsConfidential, *peIsXMLLoaded, *peIsReplyDataset, *pbStatus); |
[C/C++ return value] | S_OK | This value is returned if the function call was successful. |
 | S_FALSE | This value is returned if the end of an iteration is reached |
 | E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions. |
space
Calling argument description |  |  |
[out] LanguageType | *peDataLanguage | The language in which the data part is coded. It is exactly the language in which the notification is formulated. Note, that the data language and the module language (given by
[out] YesNoType | *peIsConfidential | A Boolean that defines if the notification thread is confidential. Note that the confidentiality status is defined at the moment of the initial XML infoset generation, thereafter it must be inherited into each new reply cycle. |
[out] YesNoType | *peIsXMLLoaded | A Boolean that defines if the data stem from a XML infoset (enYes) or if a new request was generated (enNo) using the IGeneralNotificationRequest interface. Note, that if eIsXMLLoaded=enYes then a reply can directly be made using the IGeneralNotificationRequest::SetReply method. |
[out] YesNoType | *peIsReplyDataset | A Boolean that defines if the data represents the input (enNo) or the output (enYes). This Boolean basically defines if the singularity in data space is reached meaning if the IGeneralNotificationRequest::SetReply method was called or not. |
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE then an error occurred and GetAbortInfo should be called to retrieve the error string. |
space |


  • IGeneralNotificationResponse
  • GetSender

IGeneralNotificationResponse::GetSender method |  |  | space
Retrieves the various identifiers (EAN, ZSR,...) and the structured address of the sender. Note that the sender address is mirrored and becomes the recipient address after the singularity point that is after calling IGeneralNotificationRequest::SetReply. |  |  |
space
Restful webservice calling syntax |  |  |
[POST] | /baseURL/ IGeneralNotificationResponse/GetSender
[JSON input data] | pIGeneralNotificationResponse: | longValue, //interface address
[JSON result data] | pbstrEAN: pbstrZSR: pbstrSpecialty: pIAddress: pbStatus: | "utf8StringValue", "utf8StringValue", "utf8StringValue", { pbIsPrivateAddress: true, pbstrCompanyName: "utf8StringValue", pbstrDepartment: "utf8StringValue", pbstrSalutation: "utf8StringValue", pbstrTitle: "utf8StringValue", pbstrFamilyname: "utf8StringValue", pbstrGivenname: "utf8StringValue", pbstrSubaddressing: "utf8StringValue", pbstrStreet: "utf8StringValue", pbstrPoBox: "utf8StringValue", pbstrZip: "utf8StringValue", pbstrCity: "utf8StringValue", pbstrStateCode: "utf8StringValue", pbstrCountryCode: "utf8StringValue", pbstrPhone1: "utf8StringValue", pbstrPhone2: "utf8StringValue", pbstrPhone3: "utf8StringValue", pbstrFax: "utf8StringValue", pbstrEMail: "utf8StringValue", pbstrUrl: "utf8StringValue" }, booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
C/C++ calling syntax |  |  |
HRESULT GetSender( | BSTR BSTR BSTR IAddress VARIANT_BOOL | *pbstrEAN, *pbstrZSR, *pbstrSpecialty, **pIAddress, *pbStatus); |
[C/C++ return value] | S_OK | This value is returned if the function call was successful. |
 | S_FALSE | This value is returned if the end of an iteration is reached |
 | E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions. |
space
Calling argument description |  |  |
[out] BSTR | *pbstrEAN | The EAN number of the sender as supplied by Stiftung Refdata |
[out] BSTR | *pbstrZSR | The optional ZSR number of the sender as supplied by Santesuisse |
[out] BSTR | *pbstrSpecialty | The optional specialty, i.e. FMH title of the sender. |
[out] IAddress | **pIAddress | The instance of a IAddress interface that allows to read back the structured address data. If no address is defined then the handle is NULL. |
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE then an error occurred and GetAbortInfo should be called to retrieve the error string. |
space |


  • IGeneralNotificationResponse
  • GetTransport

IGeneralNotificationResponse::GetTransport method | space
Returns the transport information that is the routing information going from a sender (from) over at least one intermediate (via) to the receiver (to). All the involved parties are defined by GLN as defined by Stiftung Refdata.
If the routing is requested over more than one intermediate, than the whole routing chain ('@'-separated) is returned in the variable 'pbstrViaEAN' .

If the parameters for the signature and encryption were set then these data are returned as well otherwise the corresponding variables are empty.

Note that the transport parameter chain is mirrored after the singularity point that is after calling IGeneralNotificationRequest::SetReply.

space
Restful webservice calling syntax
[POST] | /baseURL/ IGeneralNotificationResponse/GetTransport
[JSON input data] pIGeneralNotificationResponse: longValue, //interface address
[JSON result data] pbstrFromEAN:
pbstrViaEAN:
pbstrToEAN:
pbstrToBinDERFile:
pbStatus: 		"utf8StringValue",
"utf8StringValue",
"utf8StringValue",
"utf8StringValue",
booleanValue
[HTTP result status] | 200 | Return status 200 signals a successful method call
204 | Return status 204 (noContent) signals that the end of an iteration is reached
>= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do.
space
C/C++ calling syntax
HRESULT GetTransport( BSTR
BSTR
BSTR
BSTR
VARIANT_BOOL 		*pbstrFromEAN,
*pbstrViaEAN,
*pbstrToEAN,
*pbstrToBinDERFile,
*pbStatus);
[C/C++ return value] | S_OK | This value is returned if the function call was successful.
S_FALSE | This value is returned if the end of an iteration is reached
E_name | This value is returned if the function call was unsuccessful and an error exception was generated. Note that if you are using SmartPointers an exception is thrown under these conditions.
space
Calling argument description
[out] BSTR | *pbstrFromEAN | The EAN number of the sender as supplied by Stiftung Refdata
[out] BSTR *pbstrViaEAN The chain of intermediates supplied as '@'-separated string of GLN of the involved intermediates e.g. 'gln1@gln2'.
Each GLN is defined by Stiftung Refdata
[out] BSTR | *pbstrToEAN | The EAN number of the receiver as supplied by Stiftung Refdata
[out] BSTR | *pbstrToBinDERFile | The file name of the binary DER certificate that is the public certificate of the "to" entity.
[out,retval] VARIANT_BOOL | *pbStatus | Return status of the method. If pbStatus is VARIANT_FALSE then an error occurred and GetAbortInfo should be called to retrieve the error string.
space


  • IGeneralNotificationResponse
  • DestructGeneralNotificationResponse

IGeneralNotificationResponse::DestructGeneralNotificationResponse property |  |  | space
This property has a Restful Webservice representation only! Destructs/invalidates this IGeneralNotificationResponse interface instance. |  |  |
space
Restful webservice calling syntax |  |  |
[PUT] | /baseURL/ IGeneralNotificationResponse/PutDestructGeneralNotificationResponse
[JSON input data] | pIGeneralNotificationResponse: | longValue, //interface address
[HTTP result status] | 200 | Return status 200 signals a successful method call |
 | 204 | Return status 204 (noContent) signals that the end of an iteration is reached |
 | >= 400 | Return status >= 400 signals an unsuccessful function call. The returned JSON{errorCode: code, errorText:"text"} supplies the error message the same as GetAbortInfo() would do. |
space
Remarks |  |  |
This property has a Restful Webservice representation only! |  |  |
space |


  • Type definitions

Builtin, composite & enumeration types |  | V4.51/28 Sep 2018
The following list shows ans defines all used data types either basic builtin, composite or enumeration types that are used in the interface of the ATL COM module. |  | space
space
Data types |  | 16 types
[enumeration] AddressType | Enumerates the defined address categories. |
[builtin] BSTR | A BSTR, known as basic or binary string, is a pointer to a wide character string used by Automation data manipulation functions |
[builtin] DATE | DATE is denoting a date and time represented by a double-precision number, where midnight, January 1st, 1900 has the value 2.0, January 2nd, 1900 is 3.0, and so on. |
[enumeration] generationAttributes | List of options with which standard behavior of the XML and print generation process can be oversteered. |
[builtin] HRESULT | The HRESULT data type is a 32-bit value that is used to describe an error or warning. |
[builtin] IAddress | IAddress interface. |
[builtin] IGeneralNotificationRequest | The IGeneralNotificationRequest interface |
[builtin] IGeneralNotificationResponse | The IGeneralNotificationResponse interface |
[enumeration] LanguageType | Enumerates all supported languages. |
[enumeration] LawType | Enumerates the supported legal law set. |
[builtin] long | A 4-byte integer value. |
[enumeration] ModusType | Enumerates the defined operation mode types |
[enumeration] ObjectType | Enumerates the defined reference object types. |
[enumeration] SexType | Enumerates the defined gender categories. |
[builtin] VARIANT_BOOL | A 16 bit Boolean (True/False) value was specified |
[enumeration] YesNoType | Boolean enumerator. |
space |


  • Type definitions
  • AddressType

AddressType enumeration type |  |
Enumerates the defined address categories. |  | space
space
Set of enumeration values |  | 3 elements
enAddressUndefined: 0 | Undefined or unknown address. |
enAddressPerson: 1 | Person's address. |
enAddressCompany: 2 | Company's address. |
space


  • Type definitions
  • BSTR

BSTR type |
A BSTR, known as basic or binary string, is a pointer to a wide character string used by Automation data manipulation functions. BSTRs are wide, double-byte (Unicode) strings on 32-bit Windows platforms. | space
space
space


  • Type definitions
  • DATE

DATE type |
DATE is denoting a date and time represented by a double-precision number, where midnight, January 1st, 1900 has the value 2.0, January 2nd, 1900 is 3.0, and so on. | space
space
space


  • Type definitions
  • generationAttributes

generationAttributes enumeration type |  |
List of options with which standard behavior of the XML and print generation process can be oversteered. |  | space
space
Set of enumeration values |  | 5 elements
enGenerateXMLWithoutDocuments: 65536 | The XML infoset is generated without documents even if such documents have been added in the IGeneralNotificationRequest::AddDocument method. |
enGenerateXMLWithoutSignature: 131072 | The XML infoset is generated without applying a signature to the infoset even if the signature parameters have been defined by the IGeneralNotificationRequest::SetTransport method. |
enGenerateXMLWithoutEncryption: 262144 | The XML infoset is generated without applying the encryption to the infoset even if the encryption parameters have been defined by the IGeneralNotificationRequest::SetTransport method. |
enGenerateDowngradeToV440: 1048576 | The outcome of the XML infoset or print generation is forced according to version V440 and thus a downgrade process is taking place effectively. |
enGenerateDowngradeToV450: 2097152 |  |
space


  • Type definitions
  • HRESULT

HRESULT type |
The HRESULT data type is a 32-bit value that is used to describe an error or warning. | space
space
space


  • Type definitions
  • IAddress

IAddress type |
IAddress interface. | space
space
space


  • Type definitions
  • IGeneralNotificationRequest

IGeneralNotificationRequest type |
The IGeneralNotificationRequest interface | space
space
space


  • Type definitions
  • IGeneralNotificationResponse

IGeneralNotificationResponse type |
The IGeneralNotificationResponse interface | space
space
space


  • Type definitions
  • LanguageType

LanguageType enumeration type |  |
Enumerates all supported languages. |  | space
space
Set of enumeration values |  | 3 elements
enGerman: 1 | German |
enFrench: 2 | French. |
enItalian: 3 | Italian |
space


  • Type definitions
  • LawType

LawType enumeration type |  |
Enumerates the supported legal law set. |  | space
space
Set of enumeration values |  | 6 elements
enKVG: 0 | The designated law is KVG - "Krankenversicherungsgesetz" |
enUVG: 1 | The designated law is UVG - "Unfallversicherungsgesetz" |
enMVG: 2 | The designated law is MVG - "Militäversicherungsgesetz" |
enIVG: 3 | The designated law is IVG - "Invalidenversicherungsgesetz" |
enVVG: 4 | The designated law is VVG - "Versicherungsvertragsgesetz" |
enORG: 5 | The designated law is ORG - "Obligationenrecht" This law type is primarily for invoices e.g. of dentists. |
space


  • Type definitions
  • long

long type |
A 4-byte integer value. | space
space
space


  • Type definitions
  • ModusType

ModusType enumeration type |  |
Enumerates the defined operation mode types |  | space
space
Set of enumeration values |  | 2 elements
enProduction: 0 | Production modus. |
enTest: 1 | Test modus - the data should not be forwarded to the receiver. |
space


  • Type definitions
  • ObjectType

ObjectType enumeration type |  |
Enumerates the defined reference object types. |  | space
space
Set of enumeration values |  | 6 elements
enObjectUndef: 0 | The object reference is undefined |
enObjectCredit: 1 | The object reference is of type "Credit" |
enObjectInvoice: 2 | The object reference is of type "Invoice" |
enObjectReminder: 3 | The object reference is of type "Reminder" |
enObjectMCD: 4 | The object reference is of type "MCD" |
enObjectForm: 5 | The object reference is of type "Form" |
space


  • Type definitions
  • SexType

SexType enumeration type |  |
Enumerates the defined gender categories. |  | space
space
Set of enumeration values |  | 2 elements
enMale: 0 | Male. |
enFemale: 1 | Female. |
space


  • Type definitions
  • VARIANT_BOOL

VARIANT_BOOL type |
A 16 bit Boolean (True/False) value was specified. A value of 0xFFFF (all bits 1) indicates True; a value of 0 (all bits 0) indicates False. No other values are valid. | space
space
space


  • Type definitions
  • YesNoType

YesNoType enumeration type |  |
Boolean enumerator. |  | space
space
Set of enumeration values |  | 2 elements
enNo: 0 | No. |
enYes: 1 | Yes. |
space


 Sumex1 under a 64bit architecture...

All Sumex1 COM modules are written as 32bit managed C++ dll. As a consequence, a 64bit executable cannot load a 32bit COM dll into its process space due to the addressing differences.

Since some necessary underlying sub-modules are not available in a 64bit version, this problem must be addressed differently than by a 64bit compilation. As Microsoft suggests Sumex1 uses the out-of-process proxy approach where a 32bit COM server loads the 32bit COM dll into its process space and delegates each method call to the dll. Since a 32bit COM server exists in its own process space, the main 64bit process can handle the 64/32bit boundary without problems.

As a result, each 32bit Sumex1 COM dll has a 32bit COM server counterpart with the same name and an oopProxy prefix, e.g. oopProxyGeneralNotificationManager451.exe, where the prefix signifies the out-of-process proxy nature of the executable.

Any 64bit software now creates an instance of the 32bit oopProxy server and then calls the same methods and properties as with the 32bit COM dll. However, there is one crucial difference when using the oopProxy mechanism, namely the necessity to forcefully unload to the COM server at the end e.g. by using Marshal.ReleaseComObject() since the automatic garbage collection approach is too error prone.


 Changes from V4.50 to V4.51...

The following list shows how the transition from V4.50 to V4.51 must be made in terms of new, changed, and deleted interface methods a/o arguments.

To ease the spreading towards the new COM module even if the readiness at intermediates and insurances is yet unknown, this new version natively can load, print and generate the V4.51 as well as the previous standard V4.50. So the implementation can be done now and the activation of the V4.51 standard afterwards!

IGeneralNotificationManager
changed: IGeneralNotificationManager::LoadXML(...) method can natively load The XML infosets of type generalNotification_451.xsd and generalNotification_450.xsd.
changed: The IGeneralNotificationManager::GetXML(...) method can natively produce XML infosets of type generalNotification_451.xsd and generalNotification_450.xsd.
IGeneralNotificationRequest
new: The IGeneralNotificationRequest::SetLaw(...) method optionally can define the data for a applicable law (e.g. KVG|UVG|...) and its dependent information
IGeneralNotificationResponse
new: The IGeneralNotificationResponse::GetLaw(...) method was included to retrieve the applicable law (e.g. KVG|UVG|...) and its dependent information.
IAddress
no changes


 Notes about the encryption

XML Encryption is a specification, governed by a W3C recommendation, that defines how to encrypt the contents of an XML element. Although XML Encryption can be used to encrypt any kind of data, it is nonetheless known as "XML Encryption" because an XML element (either an EncryptedData or EncryptedKey element) contains or refers to the cipher text, keying information, and algorithms.

However, it is beyond the scope of this documentation to explain all details of a encryption or the encryption process. Detailed information about all aspects of encryption can be found at W3C.

Boundary conditions and critical aspects

  • the encryption is optional!
  • if an infoset is encrypted then the public certificate of the recipient must be used and this certificate is applied to the body element.

    Here recipient is used in terms of the communication and therefore is defined as the EAN entity given in the transport@to attribute
  • the namespace v1 of W3C http://www.w3.org/2001/04/xmlenc must be used- cf. XML Encryption Syntax and Processing
  • The encryption algorithm is fixed to PKCS1 (RSA-SHA1) (RFC 2437: RSA Cryptography Specifications)
  • The block encryption algorithm is fixed to Triple DES

The generalNotification module does obey all these conditions whenever encryption is "turned on" (cf. IGeneralNotificationRequest::SetTransport).


 VB code snippet for using the generalNotificationManager

Private Sub Notify_Click()

On Error GoTo Err_Trap

Dim bStatus As Boolean

'### GeneralNotificationManager interface
Dim generalNotificationManagerEx As GENERALNOTIFICATIONMANAGER451Lib.GeneralNotificationManager
Set generalNotificationManagerEx = New GeneralNotificationManager

'### GeneralNotificationRequest
Dim generalNotificationRequestEx As GENERALNOTIFICATIONMANAGER451Lib.GeneralNotificationRequest
Set generalNotificationRequestEx = generalNotificationManagerEx.GeneralNotificationRequest

'### initialize the request interface in germand and as confidential
bStatus = generalNotificationRequestEx.Initialize(enGerman, enYes)

Dim IAddress As GENERALNOTIFICATIONMANAGER451Lib.Address
Set IAddress = generalNotificationRequestEx.CreateAddress

'### set notification parameters
Dim strNotificationID As String
strNotificationID = "N3000"
Dim dNotificationDate As Date
dNotificationDate = DateValue("2010-9-21")
Dim lNotificationTimestamp As Long
lRequestTimestamp = 1316590422

bStatus = generalNotificationRequestEx.SetNotification(strNotificationID, dNotificationDate,  _
                                                       lNotificationTimestamp)

'### set transform
Dim strFromEAN As String
strFromEAN = "2000000000001"
Dim strViaEAN As String
strViaEAN = "2011111111111"
Dim strToEAN As String
strToEAN = "2034567890222"

bStatus = generalNotificationRequestEx.SetTransport(strFromEAN, "", "", strViaEAN, strToEAN, "")

'### set sender
IAddress.Initialize
bStatus = IAddress.SetPerson("Aerztin", "Patricia", "Frau", "Dr. med.", "")
bStatus = IAddress.SetPostal("Arztgasse 17b5", "", "4000", "Basel", "BS", "")
bStatus = generalNotificationRequestEx.SetSender(strFromEAN, "", "Arzt", IAddress)

'### set recipient
IAddress.Initialize
bStatus = IAddress.SetCompany("Krankenkasse AG", "Sektion Basel", "")
bStatus = IAddress.SetPostal("Kassengraben 222", "", "4000", "Basel", "", "")
bStatus = generalNotificationRequestEx.SetRecipient(strToEAN, "", "", IAddress)

'### patient
IAddress.Initialize
Dim dBirthdate As Date
dBirthdate = DateValue("1950-1-1")
bStatus = IAddress.SetPerson("Muster", "Peter", "Herr", "", "c/o Mieter Karl")
bStatus = IAddress.SetPostal("Musterstrasse 5", "", "7304", "Maienfeld", "", "")
bStatus = generalNotificationRequestEx.SetPatient(eSex, dBirthdate, "756.1234.5678.90", IAddress)

'### set message
Dim strMessage As String
strMessage = "A test message!"
bStatus = generalNotificationRequestEx.SetMessage(strMessage, "")

bStatus = generalNotificationRequestEx.Finalize()

'### get the notification xml
Dim lGenerationAttributes As Long
lGenerationAttributes = 0
Dim strOutFile As String
Dim lValidationError As Long
lValidationError = 0
Dim lTimestamp As Long
lTimestamp = 0

Dim generalNotificationResponseEx As GENERALNOTIFICATIONMANAGER451Lib.GeneralNotificationResponse

bStatus = generalNotificationManagerEx.GetXML(lGenerationAttributes, strOutFile, lValidationError, lTimestamp,  _
                                              generalNotificationResponseEx)

Dim strTargetFile As String
strTargetFile = "GeneralNotificationExample.xml"
FileCopy strOutFile, strTargetFile

Exit Sub

Err_Trap:
    MsgBox "Error: " & Err.Description, vbCritical, _
           "Opps! Error" & Str$(Err.Number)
'### relase resources
Set generalNotificationResponseEx = Nothing
Set generalNotificationRequestEx = Nothing
Set generalNotificationManagerEx = Nothing

End Sub


 General use of the generalNotification ATL COM module

The generalNotificationManager is an ATL COM module which provides methods the generate an email like structured message exchange between to partners. The produced XML infoset is transported electronically to the recipient and can optionally can be signed and/or encrypted.

Architectural blueprint
Either a new notification is produced from scratch by using the IGeneralNotificationRequest interface or a received notification is loaded into the module by the LoadXML method and a reply to that message is generated thereafter. The all data can be visualized using the Print method.
New notification
To produce such an infoset, firstly an instance of the IGeneralNotificationRequest interface is retrieved by the property IGeneralNotificationManager::GetGeneralNotificationRequest. Thereafter the relevant data is set.

Reply to a notification
Firstly load the XML infoset by calling the IGeneralNotificationManager::LoadXML method. To view the data call the IGeneralNotificationManager::Print method. And lastly set a reply by using the IGeneralNotificationRequest::SetReply method.

After all information is defined the data can be visualized by using the IGeneralNotificationManager::Print method. Eventually the data is transformed into a standards-compliant generalNotification XML infoset that is sent to the recipient over a intermediate.

To get a staring point with the generalNotification module there is a Visual Basic code snippet provided that can be used for generating a notification.


 How to generate PDF archive files of a notification

To generate PDF archive files of a notification in the generalNotificationManager use a special print object name (cf. Syntax of the printTemplate variable for an overview).

(PDF=PDF_file_to_generate;)
or
(PDF_NOPRINT=PDF_file_to_generate;)
is used as a print object name on the printTemplate variable of the Print method.

The "PDF" token means to print the notification and generate the PDF files, whereas the "PDF_NOPRINT" token only generates the PDF file without physical printing.
This object definition is only used while printing and is ignored in the preview mode!

In its simplest form this means

     BSTR bstrPrintTemplate = "(PDF="+bstrPDFFile+";)";

     IGeneralNotificationManager::Print(bstrPrintTemplate,...);
in order to generate a PDF archive file of notification.

Since the PDF generation is not the main purpose of the Print method this PDF feature has NO error propagation. The generation is done on a best effort basis, errors are only dumped to the log file!

Boundary conditions:

  • Only active in printing mode
  • No error propagation
  • The supplied PDF archive name must not exist
  • The directory where the PDF is stored must be writable


 Query reachability of a recipient by the medSRS webservice

medSRS.ch is an open routing service for standards of the Forum Datenaustausch, basically allowing to find a communication partner in function of/for a certain Forum Datenaustausch standard.

The Routing Half Set (RHS) consists of a set of Global Location Numbers (GLN) plus the targeting Forum Datenaustausch standard forming an address path to an intermediate.

glnProvider(standardName, glnIntermediate, glnFrom)

In this notation, a provider is bounded to an intermediate with a certain standard having the given GLN at that intermediate. By using the query interface of medSRS, the RHS of a searched communication partner is returned.

The medSRS service is accessible, managed, and queried by a RESTful webservice defined and build upon the state of the art OpenAPI 3.0 standard. Please consult the medSRS.ch website directly for an in-depth introduction to the principles and objectives of the medSRS service and the associated RESTful web service calls.

Patch of the IGeneralNotificationRequest::SetTransport method

Important new feature: the electronic reachability of a recipient for a certain version of generalNotification is kind of chicken and egg problem. To solve this connectivity problem, the webservice medSRS (medical Standard Routing Service) has been created. By using the RESTful webservice method queryRHS one can find out, how and whether a specific recipient can be reached electronically. Please refer to the website medSRS.ch for getting an introduction to the topic or detailed information about the functionality of the webservice.

Instead of inputting the argument bstrToEan literal, the string queryRHS(glnProvider,glnRecipient) is supplied virtually as a webservice call in the IGeneralNotificationRequest::SetTransport method. The such given data is actually translated into the RESTful call of the same name. Furthermore, should the query result indicate an unreachability for version V451, a query check for version V450 is automatically launched to investigate on the lower version. If the downgraded version is supported, than everything is prepared internally such that the method IGeneralNotificationManager::GetXML generates a downgrade automatically and transparently.

The usage of the patch can generate a new error code 'ERROR_RECIPIENTRHS_NOTAVAILABLE' indicating that a given recipient is not reachable. It is the decision of the calling program whether the error 'ERROR_RECIPIENTRHS_NOTAVAILABLE' will be considered or not.


 Syntax of the printTemplate variable of the Print method

bstrPrintTemplate argument of the IGeneralNotificationManager::Print is either empty or of the general form given below.

If the bstrPrintTemplate variable is empty then the default print template (using the data language as language switch) is used.
However, bstrPrintTemplate can be used to change the normal printing behavior or changing printing objects dynamically. The following syntax is used as content of the bstrPrintTemplate variable:

[logTpl][(objectName1=text;...)][=printTemplateFile][#INIPATH=inipath]

where a [] pair defines an optional part. The commands are case insensitive.
  • logTpl: is the logical template name. Currently only logTpl=Detail is allowed.
  • objectName1=text; does a substitution of the content of the print object objectName1 by text. A print object is terminated by a semicolon and all print objects are enclosed in a () pair.

    There is a predefined pseudo print object with a special meaning:

    • PDF for generating PDF files

  • printTemplateFile is an external print template file name (full path + name!). If an external print template is supplied it must be mapped against a logical template. Therefore detail=full_vps_file must be used!
  • #INIPATH=inipath defines a fully qualified path to a directory where the report engine searches the corresponding .vpd print template INI file. This allows for global settings of a print template in a LAN. The default inipath is the install directory of the Dll

Here are some usage examples:
  • bstrPrintTemplate: "" or bstrPrintTemplate: Detail
    denotes a standard printing situation
  • bstrPrintTemplate: (DOCUMENT_TITLE=Alternate title for the notification;) prints a substituted title as given above.
  • bstrPrintTemplate: detail=C:\myForms\myPrintForm.vps
    uses the print template "C:\myForms\myPrintForm.vps". An optional INI file with the name "C:\myForms\myPrintForm.vpd" is searched under this condition.
  • bstrPrintTemplate: #INIPATH=\\host1\\myForms\
    the default path for the ini files (place of the installed component) is changed to "\\host1\\myForms\". If "\\host1\\myForms\" is accessible by all hosts of the LAN then the same INI settings can be used.


 Object reference...

The following paragraphs defines the concepts of object reference, object reference chain, and topmost object reference. These concepts are of high importance within the XML request/response system.

object reference

An object reference is an identification of an individual XML request defined by a unique triple of data, namely
  • timestamp (UNIX time) defined at the moment of generation
  • date of the object defined by the provider
  • id of the object defined by the provider
Each and every XML request of version 4.5 is defined by such an object reference. All XML responses are replies to the object reference of the corresponding request.

Thus the object reference is a clustered primary key of the request/response system!

object reference chain

As a consequence of the XML schema coded business logic most XML request schemas define more than just 1 object reference, e.g. a "generalNotification" needs 2 object references, namely
  • a optional object reference from another process, e.g. "General Invoice Request" or "General Credit Request"
  • a mandatory notification object reference from the main " General Notification " process
This set of object references by itself defines an ordered object reference chain (e.g. invoice -> notification) with the topmost object reference as unique identification of the XML request. Therefore the object reference chain defines -on business logic point of view- dependencies among different XML requests.

topmost object reference

The end node of an object reference chain is defined as topmost object reference, that is by definition the object reference of the XML request itself. Each request/response communication is always done for this topmost object reference and only for that.


 Introduction, overview and usage of the Restful Webservice Server

The application generalNotificationManagerServer451.exe is a Restful Webservice Server, that has the same interface methods/properties as the COM module generalNotificationManager451.dll.
This allows to create a programming semantically similar to the COM approach but under the Restful Webservice paradigm. Consequently, on the Restful Client side there are no prevailing dependencies on Microsoft platforms and/or on Microsoft resources such as the database technology. Of course, the installation location of the server software is still subject to these restrictions.

In the next section of this document, the installation, configuration and operation of generalNotificationManagerServer451.exe will be addressed.

Installation, registration and parameterization:
By installing the installer object generalNotificationManager451 the COM module generalNotificationManager451.dll as well as the out-of-process proxy component oopGeneralNotificationManager451.exe is automatically installed/registered in the system. However, the generalNotificationManagerServer451.exe must be installed manually as a system service.
generalNotificationManagerServer451.exe -help | Creates a help window with the the name and full version of the applicationb as well as the currently define Webservice Endpoint. Furthermore the complete list of command line switches is shown.
generalNotificationManagerServer451.exe -install | Installs/registers the Restful Webservice Server as a system service. Please take into account, that the installation must be performed under administrator privileges
generalNotificationManagerServer451.exe -uninstall | Uninstalls the system service component. Please take into account, that the uninstallation must be performed under administrator privileges
generalNotificationManagerServer451.exe -setport X | Sets the port X as part of the Webservice Endpoint
Restful Webservice Endpoint:
Installing generalNotificationManagerServer451.exe as a service activates the Restful Webservice Endpoint:
http://localhost:35345/generalNotificationManagerServer451
which is subsumed as baseURL in the subsequent API documentation.

To run the webservice under a different URL or under https protocol, a permanent webservice target endpoint mapping is performed on the target system.
For example, under Apache, the following rewrite rule is defined:
<VirtualHost *:*>
    ProxyPreserveHost Off
    Header always set Access-Control-Allow-Origin "*"
    Header always set Access-Control-Max-Age "1000"
    Header always set Access-Control-Allow-Headers "x-requested-with, Content-Type, origin, authorization, accept, client-security-token"

    ProxyPass /generalNotificationManager/451/ http://localhost:35345/generalNotificationManagerServer451/
    ProxyPassReverse /generalNotificationManager/451/ http://localhost:35345/generalNotificationManagerServer451/
</VirtualHost>
Restful Webservice Operation:
The service might be modified after installation, for example to start under a different account, to extend the recovery properties or to change the startup type. Finally, this should be set to 'Automatic' or 'Automatic (Delayed start)' so that the service is automatically available after a system restart.
Remarks about programming:
In the rest of this document we will discuss programming of the Restful web service and the differences to the C/C++ programming of the classic COM component.

As already mentioned, Restful programming is analogous to C++ programming with the addition that each instance of an interface (including the main interface) is created via the corresponding GET function. For example, an instance of the main interface is created with:
baseURL/IGeneralNotificationManager/GetCreateGeneralNotificationManager | returns the instance address as JSON out{pIGeneralNotificationManager: longValue,...}
In every further call of a method or a property of the main interface this instance address must be included as part of the JSON-In. The termination/deletion of an instance must be done via the corresponding PUT Destruct property:
baseURL/IGeneralNotificationManager/PutDestructGeneralNotificationManager | with JSON-In{pIGeneralNotificationManager: longValue}, deletes the corresponding main instance AND all at that moment still active dependent subinstances (subinstances which have been generated by the explicit main instance).
It should be noted that the webserver generalNotificationManagerServer451.exe performs an internal management of the generated instances and automatically deletes instances that have no activity for a defined period of 1 hour. If after the deletion a rest call with such an instance is made, an error (HTTP Status >= 400) is generated and the instance address is marked as unknown.
Code snippet:
Minimal code snippet to load an XML and produce a PDF representation of that input data:

    http://localhost:35345/generalNotificationManagerServer451/IGeneralNotificationManager/GetModuleVersion?pIGeneralNotificationManager=45467
        returns JSON-Out{pbstrModuleVersion: "1.00.010"}

    http://localhost:35345/generalNotificationManagerServer451/IGeneralNotificationManager/GetModuleLanguage?pIGeneralNotificationManager=45467
        returns JSON-Out{peLanguage: "1"}

    http://localhost:35345/generalNotificationManagerServer451/IGeneralNotificationManager/GetGeneralNotification?pIGeneralNotificationManager=45467
        returns JSON-Out{pIGeneralNotification: 5788991}

    http://localhost:35345/generalNotificationManagerServer451/IGeneralNotification/PutDestructGeneralNotification
        JSON-IN(pIGeneralNotification: 5788991}

    http://localhost:35345/generalNotificationManagerServer451/IGeneralNotificationManager/PutDestructGeneralNotificationManager
        JSON-IN{pIGeneralNotificationManager:45467}


 Notes about the signature

XML signatures are digital signatures designed for use in XML transactions. The W3C standard defines a schema for capturing the result of a digital signature operation applied to an infoset. XML signatures add authentication, data integrity, and support for non-repudiation to the data that they sign.
However, it is beyond the scope of this documentation to explain all details of a signature or the signing process. Detailed information about all aspects of signatures can be found at W3C.

Boundary conditions and critical aspects

  • the signature is optional!
  • if an infoset is signed then the private certificate of the sender must be used and this certificate is applied to the payload element. This inherently qualifies for a detached signature.

    In this context sender is used in terms of the communication and therefore is defined as the EAN entity given in the transport@from attribute

  • the URI attribute of the reference element must use a XPointer syntax of the payload element, e.g. <ds:Reference URI="#xpointer(/notification:notification/notification:payload)">
  • it is recommended to add the public key via a X509Data element such that a key store can be built at the recipient's site
  • The signature algorithm is fixed to PKCS1 (RSA-SHA1) (RFC 2437: RSA Cryptography Specifications)
  • The digest algorithm is fixed to SHA-1
  • the used canonicalization algorithm must be http://www.w3.org/2001/10/xml-exc-c14n#, the exclusive XML Canonicalization

The generalNotification module does obey all these conditions whenever signature is "turned on" by setting the private certificate and password of the "fromEAN" entity (cf. IGeneralNotificationRequest::SetTransport). This certificate must be in the PFX format.