FBoxAPI 0.1.33

FBoxAPI

Dieses Projekt ist ein .NET Bibliothek für die Schnittstellen TR-064 und AHA der AVM Fritz!Box. Das Projekt ist eine Ausgliederung aus meinem Addin für Microsoft Outlook: Fritz!Box Telefon-dingsbums V5

Dieses Addin ist in meiner Freizeit entstanden. Ich erwarte keine Gegenleistung. Ein Danke ist ausreichend. Wer mir dennoch etwas Gutes zukommen lassen möchte kann dies gerne tun:

Grundlagen

Die Schnittstelle basiert auf der AVM-Dokumentation.

Nutzung

Initialisierung

Die Verwendung ist recht einfach angedacht. Es muss eine neue FBoxAPI.FritzBoxTR64-Klasse instanziiert werden (auch für AHA). Hierfür sind zwei Parameter erforderlich: IP-Adresse der Fritz!Box und die Anmeldeinformationen. Nutzername und Passwort werden in einer neuen Instanz der System.Net.NetworkCredential-Klasse hinterlegt und übergeben. Es gibt mehrere Möglichkeiten die Schnittstelle zu initiieren.

• Übergabe der benötigten Daten als Einzel-Parameter
• Dimensionierung einer FBoxAPI.Settings-Klasse, die alle notwendigen Daten enthält

Im Folgenen ist ein kleines Beispiel aufgeführt, wie die SessionID der Fritz!Box abgefragt werden kann.

Private Function GetSessionID() As String
    ' Bereitstellung der Variable(n), in die das Ergebnis gesetzt werden sollen.
    Dim SessionID As String = "0000000000000000"

    ' Erstelle Anmeldeinformationen für die Fritz!Box bereit
    Dim Nutzername As String = "Fritz"
    Dim Passwort As String = "Box"

    ' Anmeldeinformationen können Nothing sein, falls nur Actions ausgeführt werden, die keine Anmeldung erfordern.
    Dim Anmeldeinformationen As New Net.NetworkCredential(Nutzername, Passwort)

    ' Starte die TR-064 Schnittstelle zur Fritz!Box
    Using FBoxTR064 As New FBoxAPI.FritzBoxTR64("192.168.178.1", Anmeldeinformationen)

        ' Auswahl des Service
        With FBoxTR064.Deviceconfig

            ' Action ausführen
            If .GetSessionID(SessionID) Then
                ' Alles OK: SessionID enthält eine gültige SessionID
            Else
                ' Ein Fehler ist aufgetreten
            End If
        End With

    End Using

    Return SessionID

End Function

Alternativ:

FBoxTR064 = New FBoxAPI.FritzBoxTR64(New FBoxAPI.Settings With {.Anmeldeinformationen = Anmeldeinformationen,
                                                                .FritzBoxAdresse = "192.168.178.1",
                                                                .FBAPIConnector = New FBoxAPIConnector,
                                                                .AuraService = True})

Hinweis: Wenn der AURA-Service (AVM USB Remote Access) verwendet werden soll, muss dies bei der Initialisierung der Schnittstelle übergegeben werden. Dies ist über die Eigenschaft AuraService der FBoxAPI.Settings-Klasse möglich.

Logging

Mit Hilfe des FBAPIConnector-Schnittstelle kann eine eigene Routine verknüpft werden, die das Logging übernimmt. Die Schnittstelle gibt folgende relevante Daten in der Containerklasse FBoxAPI.LogMessage für das Logging aus:

• Level (System.Enum) für das LogLevel (Trace bis Fatal)
• Message (System.String)
• Exception (System.Exception)
• CallerMemberName (System.String)
• CallerFilePath (System.String)
• CallerClassName (System.String)
• CallerLineNumber (System.String)

Beispiel für NLog:

Imports FBoxAPI

Friend Class FBoxAPILog
    Implements IFBoxAPIConnector

    Private Property NLogger As Logger = LogManager.GetCurrentClassLogger

    Public Sub LogMessage(MessageContainer As LogMessage) Implements IFBoxAPIConnector.LogMessage
        With MessageContainer
            Dim LogEvent As New LogEventInfo() With {.Level = NLog.LogLevel.FromOrdinal(MessageContainer.Level),
                                                     .LoggerName = MessageContainer.CallerClassName,
                                                     .Exception = MessageContainer.Ex,
                                                     .Message = MessageContainer.Message}

            LogEvent.SetCallerInfo(.CallerClassName, .CallerMemberName, .CallerFilePath, .CallerLineNumber)

            NLogger.Log(LogEvent)
        End With
    End Sub

    Public Sub Signal2FAuthentication(Methods As String) Implements IFBoxAPIConnector.Signal2FAuthentication
        ' ...
    End Sub
End Class

Zwei-Faktor-Authentifizierung

Die Nutzung der Zwei-Faktor-Authentifizierung kann ab Fritz!OS 7.39 nicht mehr deaktiviert werden. Das Setzen verschiedener Einstellungen bedarf nun einer zusätzlichen Bestätigung durch den Nutzer. Der Ablauf des Authentifizierungsprozesses ist in X_AVM-DE_Auth beschrieben. Sobald für eine Action eine eine Zwei-Faktor-Authentifizierung erforderlich ist, signalisiert diese API dies über die FBoxAPIConnector-Schnittstelle, welche hierfür mit der Routine Signal2FAuthentication ergänzt wurde. Der Parameter Methods enhält die erlaubten Methoden, z. B. button,dtmf;*14048. Sobald der Nutzer die Authentifizierung durchgeführt hat, wird die ursprüngliche Action erneut ausgeführt. Die Ergebnisse des Authentifizierungsprozesses werden über die LogMessage ausgegeben.

• Über die Eigenschaft AbortAuthentication kann der API signalisiert werden, dass der Authentifizierungsporzess abgebrochen werden soll.
• Über die Eigenschaft AuthenticationSuccesful signalisiert die API, dass der Authentifizierungsporzess abgeschlossen wurde.

Imports FBoxAPI

Friend Class FBoxAPILog
    Implements IFBoxAPIConnector

    Public Sub LogMessage(MessageContainer As LogMessage) Implements IFBoxAPIConnector.LogMessage
        ' ...
    End Sub

    Public Property AbortAuthentication As Boolean Implements IFBoxAPIConnector.AbortAuthentication

    Public Property AuthenticationSuccesful As Boolean Implements IFBoxAPIConnector.AuthenticationSuccesful

    Public Sub Signal2FAuthentication(Methods As String) Implements IFBoxAPIConnector.Signal2FAuthentication
        MsgBox(String.Format($"Zwei-Faktor-Authentifizierung: {Methods}"), MsgBoxStyle.Information, "Zwei-Faktor-Authentifizierung")
    End Sub
End Class

Bekannte Probleme und Hinweise

• Die Dokumentation von AVM ist nicht immer korrekt. Z. B. wird in der Dokumentation X_AVM-DE_AppSetup der Parameter MyFritzDynDNSEnabled der Action GetAppRemoteInfo aufgelistet. Dieser Parameter lautet aber NewMyFritzEnabled. Es kann nicht ausgeschlossen werden, dann auch anderer Stelle ähnliche Probleme auftreten.
• Die Services und Actions wurden per Copy&Paste aus den vorliegenden Dokumentationen zusammengestellt. Bitte habt Verständnis, dass ich nicht alles testen kann.
• Während einer laufenden Zwei-Faktor-Authentifizierung wird der aufrufende Thread blockiert.

Umsetzung

folgende angehakte TR-064 Services werden derzeit unterstützt. Falls etwas fehlen sollte, oder etwas nicht funktioniert, dann gebt bitte Bescheid.

• AURA (Inoffizielle Dokumentation von Black Senator aus dem IPPF)
• DeviceConfig
• DeviceInfo
• Hosts
• LANConfigSecurity
• LANEthernetInterfaceConfig
• LANHostConfigManagement
• Layer3Forwarding
• ManagementService
• Time
• UserInterface
• WANCommonInterfaceConfig
• WANEthernetLinkConfig
• WANDSLInterfaceConfig
• WANDSLLinkConfig
• WANIPConnection
• WANPPPConnection
• WLANConfiguration
• X_AVM-DE_AppSetup (Hinweis: Alle Argumente sind in der Dokumentation falsch angegeben. Der übliche Präfix New wurde nicht dargestellt.)
• X_AVM-DE_Auth
• X_AVM-DE_Dect
• X_AVM-DE_Filelinks
• X_AVM-DE_HostFilter
• X_AVM-DE_Media
• X_AVM-DE_MyFritz
• X_AVM-DE_OnTel
• X_AVM-DE_RemoteAccess
• X_AVM-DE_Speedtest
• X_AVM-DE_Storage
• X_AVM-DE_TAM
• X_AVM-DE_UPnP
• X_AVM-DE_USPController
• X_AVM-DE_WANMobileConnection
• X_AVM-DE_WebDAVClient
• X_HomeAuto
• X_HomePlug
• X_VoIP

Des Weiteren wird das AVM Home Automation-Interface unterstützt.

Markenrecht

Dieses Software wird vom Autor privat in der Freizeit als Hobby gepflegt. Mit der Bereitstellung der Software werden keine gewerblichen Interessen verfolgt. Es wird aus rein ideellen Gründen zum Gemeinwohl aller Nutzer einer Fritz!Box betrieben. Die Erstellung dieser Software erfolgt nicht im Auftrag oder mit Wissen der Firmen AVM GmbH. Diese Software wurde unabhängig erstellt. Der Autor pflegt im Zusammenhang mit dieser Software keine Beziehungen zur Firma AVM GmbH.