[[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@provider.nl" 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 }}}:

{{{#!csharp
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 }}}:
{{{#!csharp
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:

[[Image(protocolhandler_easidata_meting.drawio.png)]]

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 }}}: 

{{{#!csharp
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:

[[Image(protocolhandler_print_word_document.drawio.png)]]

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:

{{{#!csharp
 [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
}}}