Common calls in a communications API


Inspired by several generic interfaces in the Unix/Linux world such as the socket API, and event-driven programming, I have been using the following calls (functions or methods, and event notifications) in my communications APIs.

  • init – May be replaced by the constructor of a class. Creates resources that are held for the lifetime of this object. A corresponding call destroy may also be implemented for deterministic finalization of resources.
  • connect(configuration, callback) – Where configuration provides whatever configuration information is required for connection. It may also be passed to init or obtained by some other means. callback is invoked when connection is established. If implementing a server API, use onConnect for notification of incoming connection.
  • onConnect(connection) – Event notification when an incoming connection is established.
  • disconnect(callback) – Finalizes communication, and calls callback when done. In a server API disconnect may receive an additional parameter indicating which connection to disconnect from.
  • onDisconnect() – Event notification when a disconnection happens and disconnect has not been invoked.
  • onReceive(data) – Event notification when incoming data is received.
  • send(data) – Called when data needs to be sent. If data is an array of bytes, it may receive additional parameters such as start index and length. It may additionally receive a callback that is called when data is sent out (if the API buffers data).
  • onError(error) – Event notification when an error needs to be communicated.

Event notifications can be implemented differently in various languages. I have used callback function in C, delegates in .NET, event listeners (observers) in Java, Blocks in Objective C, and EventEmitter in Node.js.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s