[[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 eigen protocol handler om te communiceren met software en randapparatuur op het werkstation van de gebruiker. Alle OpenAC URL's die beginnen met protocol {{{openac-protocol:}}} worden door deze protocol handler afgehandeld. Dit functioneert alleen als de OpenAC protocol handler op het werkstation is geïnstalleerd en het protocol in de Windows registry is gekoppeld aan {{{ 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
}}}