TOC(heading=ProtocolHandler)? TOC(heading=Procedures, sectionindex, compact, depth=3, allactive, Documentatie/Ontwikkelaar/Procedures/)? TOC(heading=Ontwikkelaar, sectionindex, compact, depth=2, allactive, Documentatie/Ontwikkelaar/)? TOC(heading=Documentatie, sectionindex, compact, depth=1, allactive, Documentatie/)?

Protocol handler

Inleiding

OpenAC gebruikt een protocol handler om te kunnen communiceren met software en randapparatuur op het werkstation van de gebruiker. Een protocol handler is een applicatie die weet hoe moet worden omgegaan met speciale hyperlinks.

Alle hyperlinks beginnen met een schema gevolgd door ":". De bekendste schema's zijn http en https. Deze worden door de browser afgehandeld door de opgegeven pagina te laden. Een andere bekende schema is "mailto". Bij een klik op "mailto:adres@…" wordt de bij het besturingssysteem geregistreerde mail applicatie gestart.

OpenAC gebruikt het schema openac-protocol om lokaal geïnstalleerde software te starten. Alle OpenAC URL's die beginnen met schema openac-protocol: worden door deze protocol handler afgehandeld. De OpenAC protocol handler moet zijn geïnstalleerd op elk werkstation waarop lokale software moet worden gestart. Het installatieprogramma koppelt schema openac-protocol aan de OpenACProtocolHandler.exe. Hierdoor weet Windows welke applicatie moet worden gestart bij een klik op een link met schema openac-protocol:.

De communicatie tussen OpenAC 3 en de protocol handler is gebaseerd op 4 programmatische onderdelen. 2 daarvan bevinden zich aan de kant van OpenAC en 2 aan de kant van de protocol handler:

1. Sjabloonhandlers (OpenAC) - een sjabloon handler genereert de argumenten die aan de sjabloon handler moeten worden aangeleverd in de url, gebaseerd op het sjabloon;
2. Starters (protocol handler) - een starter weet welke applicatie moet worden gestart en hoe de data hiervoor moet worden opgehaald, gebaseerd op het sjabloon;
3. Print implementaties (protocol handler) - een primt implementatie weet hoe een document van een bepaald type moet worden geprint;
4. Protocol handler controllers (OpenAC) - een protocol handler controller verwerkt dataverzoeken en antwoorden van de protocol handler.

Sjabloonhandlers

Een sjabloon handler genereert de argumenten die aan de sjabloon handler moeten worden aangeleverd in de url, gebaseerd op het sjabloon.

Sjabloonhandlers zijn in het OpenACLogica project terug te vinden onder de module Bestanden in de map Sjabloonhandlers .

Elke sjabloonhandler implementeert de interface ISjabloonhandler :

namespace OpenACLogica.Modules.Bestanden.Sjabloonhandlers
{
    public interface ISjabloonhandler
    {
        IEnumerable<string> RegisterFor { get; }
        string Name { get; }
        SjabloonInfo Create(SjabloonInfo sjabloonInfo, string user, List<LookupItem> themas = null, Dictionary<string, string> args = null);
        SjabloonInfo Display(SjabloonInfo sjabloonInfo, string user, List<LookupItem> themas = null, Dictionary<string, string> args = null);

    }
}

Starters

Een starter weet welke applicatie moet worden gestart en hoe de data hiervoor moet worden opgehaald, gebaseerd op het sjabloon.

Starters zijn in het OpenACProtocolHandler project te vinden in de map Starters . In dezelfde map bevindt zich de klasse Starter . Deze klasse heeft een method Get die een starter teruggeeft op basis van een ProtocolArgument .

Elke starter implementeert de interface IApplicatieStarter :

namespace OpenACProtocolHandler.Interfaces
{
    public interface IApplicatieStarter
    {
        Result Start(ProtocolArgument args);
    }
}

Als illustratie van de communicatie tussen OpenAC en de protocol handler voor het starten van een applicatie, onderstaand een sequence diagram voor het starten van een EasiData meting:

De sequence begint linksboven. Van boven naar beneden volgen de volgende gebeurtenissen elkaar op:

1. OpenAC verstuurt een bericht aan de protocol handler om EasiData meting te starten (conceptueel, in werkelijkheid genereert OpenAC een protocol handler URL. Door een klik op de link start Windows de handler die in de registry is gekoppeld aan het openac-protocol schema.);
2. De protocol handler verstuurt een bericht aan OpenAC om de metadata voor de meting op te halen;
3. De protocol handler verstuurt een bericht aan EasiData om een meting te starten. Dit gebeurt door een XML-bestand met metadata te plaatsen op een plek waar EasiData dat verwachte en daarna de EasiData excecutable op te starten.

Printimplementaties

Een primt implementatie weet hoe een document van een bepaald type moet worden geprint.

Print implementaties zijn in het OpenACProtocolHandler project te vinden in de map PrintImplementaties . In dezelfde map bevindt zich de klasse PrintImplementatie . Deze klasse heeft een method Get die een print implementatie teruggeeft op basis van een ProtocolArgument .

Elke print implementatie implementeert de interface IPrintImplementatie :

namespace OpenACProtocolHandler.Interfaces
{
    public interface IPrintImplementatie
    {
        Result Print();
    }
}

Als illustratie van de communicatie tussen OpenAC en de protocol handler voor het printen van een bestand, onderstaand een sequence diagram voor het printen van een Microsoft Word document:

De sequence begint linksboven. Van boven naar beneden volgen de volgende gebeurtenissen elkaar op:

1. OpenAC verstuurt een bericht aan de protocol handler om een document te printen (conceptueel, in werkelijkheid genereert OpenAC een protocol handler URL. Door een klik op de link start Windows de handler die in de registry is gekoppeld aan het openac-protocol schema.);
2. De protocol handler verstuurt een bericht aan Microsoft Word op het werkstation van de gebruiker om het document te openen. Dit gebeurt met een COM-koppeling;
3. Microsoft Word verstuurt een bericht aan de WebDAV server om het document te openen;
4. De WebDAV server verstuurt een bericht aan OpenAC 3 om de gebruiker te authenticeren;
5. De protocol handler verstuurt een bericht aan Microsoft Word om het document te printen.

Protocolhandler controllers

Een protocol handler controller verwerkt dataverzoeken en antwoorden van de protocol handler. Het is een normale controller maar moet zijn voorzien van een ProtocolHandlerAuthorization attribuut:

 [HttpGet]
 [Route("api/mailmerge/labeldata")]
 [ProtocolHandlerAuthorization]
 public async Task<ActionResult<Datasheet.Datasheet>> GetLabelData([FromQuery] string bestand)
 {
 }

ProtocolHandlerAuthorization zorgt ervoor dat de door de protocol handler meegestuurde JWT-token in de security header wordt gecontroleerd. Als er geen JWT-token is aangeleverd of als de JWT-token niet kan worden gevalideerd dan volgt een 401 - Unauthorized respons.

Registry

De protocol handler installer maakt gebruik van de volgende keys in de registry:

Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog\Application\OpenACProtocolHandler\EventMessageFile

D:\Program Files (x86)\OpenAC Protocol Handler\runtimes\win\lib\netcoreapp3.1\System.Diagnostics.EventLog.Messages.dll

Computer\HKEY_CLASSES_ROOT\openac-protocol

URL:openac-protocol Protocol