NCP server¶
ncplib
allows you to create a NCP server and respond to incoming NCP client connections.
Overview¶
Defining a connection handler¶
A connection handler is a coroutine that starts whenever a new NCP client connects to the server. The provided
Connection
allows you to receive incoming NCP commands as Field
instances.
async def client_connected(connection):
pass
When the connection handler exits, the Connection
will automatically close.
Listening for an incoming packet¶
When writing a NCP server, you most likely want to wait for the connected client to execute a command. Within your
client_connected
function, Listen for an incomining NCP field using Connection.recv()
.
field = await connection.recv()
Alternatively, use the Connection
as an async iterator to loop over multiple NCP field replies:
async for field in connection:
pass
Important
The async for loop will only terminate when the underlying connection closes.
Accessing field data¶
The return value of Connection.recv()
is a Field
, representing a NCP field.
Access information about the NCP field and enclosing NCP packet:
print(field.packet_type)
print(field.name)
Access contained NCP parameters using item access:
print(field["FCTR"])
Replying to the incoming field¶
Send a reply to an incoming Field
using Field.send()
.
field.send(ACKN=1)
Putting it all together¶
A simple client_connected
callback might like this:
async def client_connected(connection):
async for field in connection:
if field.packet_type == "DSPC" and field.name == "TIME":
field.send(ACNK=1)
# Do some more command processing here.
else:
field.send(ERRO="Unknown command", ERRC=400)
break
Start the server¶
Start a new NCP server.
loop = asyncio.get_event_loop()
server = loop.run_until_complete(_start_server(client_connected))
try:
loop.run_forever()
finally:
server.close()
loop.run_until_complete(server.wait_closed())
Advanced usage¶
API reference¶
-
ncplib.
start_server
(client_connected: Callable[[ncplib.connection.Connection], Awaitable[None]], host: str = '0.0.0.0', port: Optional[int] = None, *, timeout: int = 60, start_serving: bool = True, ssl: Optional[ssl.SSLContext] = None, authenticate: Optional[Callable[[str, str], bool]] = None) → asyncio.base_events.Server¶ Creates and returns a new
Server
on the given host and port.Parameters: - client_connected – A coroutine function taking a single
Connection
argument representing the client connection. When the connection handler exits, theConnection
will automatically close. If the client closes the connection, the connection handler will exit. - host (str) – The host to bind the server to.
- port (int) – The port to bind the server to.
- timeout (int) – The network timeout (in seconds). Applies to: creating server, receiving a packet, closing connection, closing server.
- start_serving (bool) – Causes the created server to start accepting connections immediately.
- ssl (ssl.SSLContext) – Start the server using an encrypted (TLS) connection.
- authenticate – A callable taking a username and password argument, returning True if the authentication is successful, and false if not. When present, authentication is mandatory.
Returns: The created
Server
.Return type: Server
- client_connected – A coroutine function taking a single