Network.Telnet.LibTelnet

Getting Started:

1. Skim the libtelnet documentation, as these bindings follow the C library's conventions quite closely.
2. Write an event-handling function, of type EventHandler.
3. When you accept a new connection, create a Telnet state tracker for it using telnetInit. Options and flags are defined in the same way as the C library; option constants are exported from Network.Telnet.LibTelnet.Options.
4. When you receive data (probably on a socket), tell Telnet about it using telnetRecv.
5. To send data, negotiate options, &c., use telnetSend, telnetIac, &c.
6. IAC (Interpret-As-Command) codes are exported from Network.Telnet.LibTelnet.Iac.

Documentation

telnetInit :: [OptionSpec] -> [Flag] -> EventHandler -> IO Telnet

Create a libtelnet state tracker.

data OptionSpec

Configures which options you want to support. The triple's elements are: option code, support on our end (corresponds to WILL/WONT), support on their end (corresponds to DO/DONT).

Constructors

OptionSpec

Fields

• _code :: Option

  Option code

• _us :: Bool

  Supported on our end? (WILL/WONT)

• _him :: Bool

  Can other end use it with us? (DO/DONT)

Instances

Eq OptionSpec

Defined in Network.Telnet.LibTelnet

Methods

(==) :: OptionSpec -> OptionSpec -> Bool

(/=) :: OptionSpec -> OptionSpec -> Bool

Show OptionSpec

Defined in Network.Telnet.LibTelnet

Methods

showsPrec :: Int -> OptionSpec -> ShowS

show :: OptionSpec -> String

showList :: [OptionSpec] -> ShowS

Generic OptionSpec

Defined in Network.Telnet.LibTelnet

Associated Types

type Rep OptionSpec :: Type -> Type

Methods

from :: OptionSpec -> Rep OptionSpec x

to :: Rep OptionSpec x -> OptionSpec

type Rep OptionSpec

Defined in Network.Telnet.LibTelnet

type Rep OptionSpec = D1 (MetaData "OptionSpec" "Network.Telnet.LibTelnet" "libtelnet-0.1.0.0-FZXraNOtRYpGr85da3Gc4W" False) (C1 (MetaCons "OptionSpec" PrefixI True) (S1 (MetaSel (Just "_code") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Option) :*: (S1 (MetaSel (Just "_us") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Bool) :*: S1 (MetaSel (Just "_him") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Bool))))

data Flag

Flags for telnet_init.

flagProxy :: Flag

Telnet pointers

type Telnet = ForeignPtr TelnetT

Garbage-collected pointer to the libtelnet state tracker. Your program should hang on to this.

type TelnetPtr = Ptr TelnetT

Raw pointer to the libtelnet state tracker. This is passed to the event handlers and you shouldn't see it elsewhere.

class HasTelnetPtr t where

The pointer you get back from telnetInit is a ForeignPtr because it carries around its finalizers, but the pointer that gets passed into your EventHandler is a bare Ptr because it's being passed in from C. This class lets us generalise across both types.

Methods

withTelnetPtr :: t -> (TelnetPtr -> IO a) -> IO a

Instances

HasTelnetPtr TelnetPtr

No unwrapping needed.

Defined in Network.Telnet.LibTelnet

Methods

withTelnetPtr :: TelnetPtr -> (TelnetPtr -> IO a) -> IO a

HasTelnetPtr Telnet

Unwrap with withForeignPtr.

Defined in Network.Telnet.LibTelnet

Methods

withTelnetPtr :: Telnet -> (TelnetPtr -> IO a) -> IO a

Event handling

type EventHandler = TelnetPtr -> Event -> IO ()

Type of the event handler callback.

data Event

Structure provided to the event handler.

Constructors

Received ByteString

Data received; you should pass it to the application.

Send ByteString

Data you need to send out to the socket.

Warning Err

Something has gone wrong inside of libtelnet but recovery is (likely) possible.

Error Err

Something has gone wrong. The application should immediately close the connection.

Iac Iac

Telnet interpret-as-command.

Will Option

Other end offers an option.

Wont Option

Other end cannot support option.

Do Option

Other end asked you to support option.

Dont Option

Other end asked you to stop using option.

Subnegotiation Option ByteString

Subnegotiation received for some option.

Zmp [ByteString]

Zenith Mud Protocol message

TerminalTypeSend

TERMINAL-TYPE SEND message (RFC 1091). The server wants to know about your terminal-type.

TerminalTypeIs ByteString

TERMINAL-TYPE IS message (RFC 1091). The client has told us a terminal-type.

Compress Bool

Would the client like MCCP Version 2?

EnvironSend [(Var, ByteString)]

Request to send the following environment variables, per (RFC 1408) and (RFC 1572).

Environ IsInfo [(Var, ByteString, ByteString)]

ENVIRON/NEW-ENVIRON options, per (RFC 1408) and (RFC 1572). Keys come before values in the tuples.

Mssp [(ByteString, [ByteString])]

Mud Server Status Protocol List is (key, values).

Instances

Eq Event

Defined in Network.Telnet.LibTelnet

Methods

(==) :: Event -> Event -> Bool

(/=) :: Event -> Event -> Bool

Show Event

Defined in Network.Telnet.LibTelnet

Methods

showsPrec :: Int -> Event -> ShowS

show :: Event -> String

showList :: [Event] -> ShowS

Generic Event

Defined in Network.Telnet.LibTelnet

Associated Types

type Rep Event :: Type -> Type

Methods

from :: Event -> Rep Event x

to :: Rep Event x -> Event

type Rep Event

Defined in Network.Telnet.LibTelnet

type Rep Event = D1 (MetaData "Event" "Network.Telnet.LibTelnet" "libtelnet-0.1.0.0-FZXraNOtRYpGr85da3Gc4W" False) ((((C1 (MetaCons "Received" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 ByteString)) :+: C1 (MetaCons "Send" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 ByteString))) :+: (C1 (MetaCons "Warning" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Err)) :+: C1 (MetaCons "Error" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Err)))) :+: ((C1 (MetaCons "Iac" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Iac)) :+: C1 (MetaCons "Will" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Option))) :+: (C1 (MetaCons "Wont" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Option)) :+: C1 (MetaCons "Do" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Option))))) :+: (((C1 (MetaCons "Dont" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Option)) :+: C1 (MetaCons "Subnegotiation" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Option) :*: S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 ByteString))) :+: (C1 (MetaCons "Zmp" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 [ByteString])) :+: C1 (MetaCons "TerminalTypeSend" PrefixI False) (U1 :: Type -> Type))) :+: ((C1 (MetaCons "TerminalTypeIs" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 ByteString)) :+: C1 (MetaCons "Compress" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Bool))) :+: (C1 (MetaCons "EnvironSend" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 [(Var, ByteString)])) :+: (C1 (MetaCons "Environ" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 IsInfo) :*: S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 [(Var, ByteString, ByteString)])) :+: C1 (MetaCons "Mssp" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 [(ByteString, [ByteString])])))))))

data Err

Error message from libtelnet.

Constructors

Err

Fields

• _file :: ByteString
• _func :: ByteString
• _msg :: ByteString
• _line :: Int
• _errcode :: TelnetErrorT

Instances

Eq Err

Defined in Network.Telnet.LibTelnet

Methods

(==) :: Err -> Err -> Bool

(/=) :: Err -> Err -> Bool

Show Err

Defined in Network.Telnet.LibTelnet

Methods

showsPrec :: Int -> Err -> ShowS

show :: Err -> String

showList :: [Err] -> ShowS

Generic Err

Defined in Network.Telnet.LibTelnet

Associated Types

type Rep Err :: Type -> Type

Methods

from :: Err -> Rep Err x

to :: Rep Err x -> Err

type Rep Err

Defined in Network.Telnet.LibTelnet

type Rep Err = D1 (MetaData "Err" "Network.Telnet.LibTelnet" "libtelnet-0.1.0.0-FZXraNOtRYpGr85da3Gc4W" False) (C1 (MetaCons "Err" PrefixI True) ((S1 (MetaSel (Just "_file") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 ByteString) :*: S1 (MetaSel (Just "_func") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 ByteString)) :*: (S1 (MetaSel (Just "_msg") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 ByteString) :*: (S1 (MetaSel (Just "_line") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Int) :*: S1 (MetaSel (Just "_errcode") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 TelnetErrorT)))))

data IsInfo

Were the Environ fields sent as part of a NEW-ENVIRON IS message, or part of a NEW-ENVIRON INFO message?

Constructors

Is

Info

Instances

Eq IsInfo

Defined in Network.Telnet.LibTelnet

Methods

(==) :: IsInfo -> IsInfo -> Bool

(/=) :: IsInfo -> IsInfo -> Bool

Show IsInfo

Defined in Network.Telnet.LibTelnet

Methods

showsPrec :: Int -> IsInfo -> ShowS

show :: IsInfo -> String

showList :: [IsInfo] -> ShowS

data Var

In an Environ message, are the vars being sent as VARs or USERVARs?

Constructors

Var

UserVar

Instances

Eq Var

Defined in Network.Telnet.LibTelnet

Methods

(==) :: Var -> Var -> Bool

(/=) :: Var -> Var -> Bool

Show Var

Defined in Network.Telnet.LibTelnet

Methods

showsPrec :: Int -> Var -> ShowS

show :: Var -> String

showList :: [Var] -> ShowS

Simple operations

telnetRecv :: HasTelnetPtr t => t -> ByteString -> IO ()

Tell the state tracker about received data.

telnetSend :: HasTelnetPtr t => t -> ByteString -> IO ()

Send non-command data.

Generic telnet option negotiation

telnetIac :: HasTelnetPtr t => t -> Iac -> IO ()

Send a telnet command.

telnetNegotiate :: HasTelnetPtr t => t -> Iac -> Option -> IO ()

Send a negotiation command.

telnetSubnegotiation :: HasTelnetPtr t => t -> Option -> ByteString -> IO ()

Send a subnegotiation.

Compression (MCCP2)

telnetBeginCompress2 :: HasTelnetPtr t => t -> IO ()

Begin sending compressed data, using the COMPRESS2 option. The server should call this command in response to a Compress True event.

NEW-ENVIRON functions (RFC 1572)

telnetNewEnvironSend :: HasTelnetPtr t => t -> [(Var, ByteString)] -> IO ()

Ask the client to send us these environment variables.

telnetNewEnviron :: HasTelnetPtr t => t -> IsInfo -> [(Var, ByteString, ByteString)] -> IO ()

Tell the server about our environment variables.

TERMINAL-TYPE functions (RFC 1091)

telnetTTypeSend :: HasTelnetPtr t => t -> IO ()

Ask the client to give us a terminal type.

telnetTTypeIs :: HasTelnetPtr t => t -> ByteString -> IO ()

Tell the server a terminal type.

ZMP (Zenith Mud Protocol)

telnetSendZmp :: HasTelnetPtr t => t -> [ByteString] -> IO ()

Send a ZMP command.

MSSP (Mud Server Status Protocol)

telnetSendMssp :: HasTelnetPtr t => t -> [(ByteString, [ByteString])] -> IO ()

Send an MSSP status.

Exceptions

data TelnetException

Exceptions thrown by the binding, for when something has gone seriously wrong. Errors detected by libtelnet are not thrown but instead are passed to the event handler.

Constructors

NullTelnetPtr

UnexpectedEventType TelnetEventTypeT

UnexpectedEnvironCmd ECmd

UnexpectedEnvironVar EVar

UnexpectedTerminalTypeCmd TCmd

Instances

Eq TelnetException

Defined in Network.Telnet.LibTelnet.Types

Methods

(==) :: TelnetException -> TelnetException -> Bool

(/=) :: TelnetException -> TelnetException -> Bool

Show TelnetException

Defined in Network.Telnet.LibTelnet.Types

Methods

showsPrec :: Int -> TelnetException -> ShowS

show :: TelnetException -> String

showList :: [TelnetException] -> ShowS

Generic TelnetException

Defined in Network.Telnet.LibTelnet.Types

Associated Types

type Rep TelnetException :: Type -> Type

Methods

from :: TelnetException -> Rep TelnetException x

to :: Rep TelnetException x -> TelnetException

Exception TelnetException

Defined in Network.Telnet.LibTelnet.Types

Methods

toException :: TelnetException -> SomeException

fromException :: SomeException -> Maybe TelnetException

displayException :: TelnetException -> String

type Rep TelnetException

Defined in Network.Telnet.LibTelnet.Types

type Rep TelnetException = D1 (MetaData "TelnetException" "Network.Telnet.LibTelnet.Types" "libtelnet-0.1.0.0-FZXraNOtRYpGr85da3Gc4W" False) ((C1 (MetaCons "NullTelnetPtr" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "UnexpectedEventType" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 TelnetEventTypeT))) :+: (C1 (MetaCons "UnexpectedEnvironCmd" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 ECmd)) :+: (C1 (MetaCons "UnexpectedEnvironVar" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 EVar)) :+: C1 (MetaCons "UnexpectedTerminalTypeCmd" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 TCmd)))))