1.2.2.1 Networking Presentation Layer

The MPLAB Harmony Networking Presentation Layer is an abstracted middleware layer that provides an encrypted channel. There are three interfaces for the layer:

Client - this interface starts a network session and reads and writes clear text data Provider - this interface encrypts the clear text into cipher text, and decrypts cipher text into clear text Transport - this interface transmits and receives the cipher text The linkage to the provider interface is done through function pointers to isolate it from the rest of MPLAB Harmony. This allows for any provider to be used. Please note that Microchip does not supply a commercially licensed TLS provider. wolfSSL (formerly CyaSSL) is supported as a provider for evaluation purposes only.

The transport interface is abstracted to function pointers as well, to allow for any transport to be used. Currently, only the MPLAB Harmony TCP/IP Stack is used as a transport; however, other transports can be created, such as UART transport, which can be used instead.

The MPLAB Harmony Networking Presentation Layer has a Tasks function that is used to continuously call the provider's connect and accept functions until they run to success of failure, thereby hiding this job from the application.

Abstraction Model

Library Overview

The Library Interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the Networking Presentation Layer.


Library Interface Section	Description
System Functions	Provides "initialize" functions and a "tasks" function for performing general presentation layer tasks.
Socket Functions	Provides various socket-related functions for the purpose of connecting, flushing, and setting options, among others.
Certificate Store Functions	Provides certificate-related functions for the purpose of obtaining certificates and keys.

Configuring the Library

The configuration of the Networking Presentation Layer is done as part of the MPLAB Harmony TCP/IP Stack configuration and specific NET_PRES parameters are generated in the configuration.h.

This header file contains the configuration selection for the Networking Presentation Layer. Based on the selections made, the Networking Presentation Layer may support the selected features. These configuration settings will apply to all instances of the Networking Presentation Layer.

This header can be placed anywhere; however, the path of this header needs to be present in the include search path for a successful build. Refer to the TCP/IP Demonstrations Help section for more details.

Library Interface

This section describes the Application Programming Interface (API) functions of the Networking Presentation Layer.


Name	Description
System Functions
NET_PRES_Deinitialize	Deinitializes the Network Presentation Layer Instance.
NET_PRES_Initialize	Initializes the Network Presentation Layer sub-system with the configuration data.
NET_PRES_Reinitialize	Reinitializes the instance of the presentation layer.
NET_PRES_Tasks	MPLAB Harmony tasks function used for general presentation layer tasks.
NET_PRES_Status	Provides the current status of the MPLAB Harmony Networking Presentation Layer.
Socket Functions
NET_PRES_SocketBind	Binds a socket to a local address.
NET_PRES_SocketClose	Disconnects an open socket and destroys the socket handle, releasing the associated resources.
NET_PRES_SocketConnect	Connects a client socket.
NET_PRES_SocketDiscard	Discards any pending data in the RX FIFO.
NET_PRES_SocketDisconnect	Disconnects an open socket.
NET_PRES_SocketEncryptSocket	This function turns an insecure socket into a secure socket. Details: This function will turn an unencrypted socket into an encrypted socket and starts encryption negotiation.
NET_PRES_SocketFlush	Immediately transmits all pending TX data.
NET_PRES_SocketGetTransportHandle	This function returns the transport layer handle. Details: This function returns the transport layer handle for a valid socket
NET_PRES_SocketInfoGet	Obtains information about a currently open socket.
NET_PRES_SocketIsConnected	Determines whether a socket has an established connection.
NET_PRES_SocketIsNegotiatingEncryption	This function checks if encryption negotiation is still in progress.
NET_PRES_SocketIsOpenModeSupported	Checks to see if a mode is supported by open.
NET_PRES_SocketIsSecure	This function checks whether a connection is secure.
NET_PRES_SocketLastError	This function returns the last error code for this socket. Details: This function will return the last error code that was set for this socket and it will clear the current error code. An error code is set whenever a socket operation fails for some missing functionality, bad parameter, etc.
NET_PRES_SocketOpen	Opens a presentation socket.
NET_PRES_SocketOptionsGet	Allows the options for a socket such as, current RX/TX buffer size, etc., to be obtained.
NET_PRES_SocketOptionsSet	Allows setting options to a socket like adjust RX/TX buffer size, etc.
NET_PRES_SocketPeek	Reads a specified number of data bytes from the RX buffer/FIFO without removing them from the buffer.
NET_PRES_SocketRead	Reads an array of data bytes from a socket's RX buffer/FIFO.
NET_PRES_SocketReadIsReady	Determines how many bytes can be read from the RX buffer.
NET_PRES_SocketRemoteBind	Binds a socket to a remote local address.
NET_PRES_SocketSignalHandlerDeregister	Deregisters a previously registered socket signal handler.
NET_PRES_SocketSignalHandlerRegister	Registers a socket signal handler.
NET_PRES_SocketWasReset	Self-clearing semaphore indicating socket reset.
NET_PRES_SocketWrite	Takes a buffer and sends it to the encryption provider.
NET_PRES_SocketWriteIsReady	Determines how much free space is available in the TX buffer.
Certificate Store Functions
NET_PRES_CertStoreGetCACerts	This function gets the CA certificates from the store,
NET_PRES_CertStoreGetServerCert	This function gets a server certificate and key from the certificate store.
Data Types and Constants
_NET_PRES_EncProviderObject	Defines the data that the presentation layer needs from the provider.
_NET_PRES_TransportObject	Defines the data that the transport layer needs to provide to the Networking Presentation Layer.
NET_PRES_INDEX	Sets the type for the presentation layer index.
NET_PRES_INIT_DATA	Initializes a Presentation layer.
NET_PRES_INST_DATA	Initializes a Presentation layer.
NET_PRES_SIGNAL_FUNCTION	MPLAB Harmony Networking Presentation Layer Signal function.
NET_PRES_SIGNAL_HANDLE	Sets the type for the presentation layer signal handle.
NET_PRES_SKT_HANDLE_T	Sets the type for the presentation layer socket handle.
NET_PRES_ADDRESS	NET_PRES address
NET_PRES_EncProviderConnect	Connects the function to the provider.
NET_PRES_EncProviderConnectionClose	Defines the close function to the provider.
NET_PRES_EncProviderDeinit	Defines the deinitialization function for the provider.
NET_PRES_EncProviderInit	Defines the initialization function to the encryption provider.
NET_PRES_EncProviderIsInitialized	Determines whether the encryption provider has been initialized.
NET_PRES_EncProviderObject	Defines the data that the presentation layer needs from the provider.
NET_PRES_EncProviderOpen	Defines the open connection function to the provider.
NET_PRES_EncProviderRead	Defines the read function to the provider
NET_PRES_EncProviderWrite	Defines the write function to the provider.
NET_PRES_EncSessionStatus	Defines the enumeration for the state and status of the encrypted portion of a connection.
NET_PRES_SKT_ADDR_T	NET_PRES address type
NET_PRES_SKT_ERROR_T	NET_PRES error type
NET_PRES_SKT_OPTION_TYPE	NET_PRES option type
NET_PRES_SKT_PORT_T	Sets the type for the presentation layer port.
NET_PRES_SKT_T	NET_PRES socket type
NET_PRES_TRANS_ADDR_T	Defines a generic address structure to pass to the transport layer.
NET_PRES_TRANS_ADDRESS_TYPE	Defines the enumeration for the type of address.
NET_PRES_TRANS_OPTION_T	Defines the enumeration for the type of options.
NET_PRES_TransBind	Binds a socket to a local address.
NET_PRES_TransBool	Generic function prototype for functions that return a bool.
NET_PRES_TransClose	Function prototype for functions that closes a socket.
NET_PRES_TransDiscard	Function prototype for functions that clears a socket's RX buffer.
NET_PRES_TransHandlerRegister	Function prototype that registers a handler with a socket.
NET_PRES_TransOpen	Opens a presentation socket.
NET_PRES_TransOption	Sets of gets a socket's options.
NET_PRES_TransPeek	Function prototype for functions that peeks on the socket's buffer.
NET_PRES_TransportObject	Defines the data that the transport layer needs to provide to the Networking Presentation Layer.
NET_PRES_TransRead	Defines the read function provided by the transport layer.
NET_PRES_TransReady	Defines the ready function provided by the transport layer.
NET_PRES_TransSignalHandlerDeregister	Function prototype that deregisters a handler with a socket.
NET_PRES_TransSocketInfoGet	Function prototype for functions that gets the information on a socket.
NET_PRES_TransWrite	Defines the write function provided by the transport layer.
NET_PRES_INVALID_SOCKET	Invalid socket indicator macro.
NET_PRES_CERTSTORE_H	This is macro NET_PRES_CERTSTORE_H.
NET_PRES_ENCRYPTION_PROVIDER_API_H	This is macro NET_PRES_ENCRYPTION_PROVIDER_API_H.
NET_PRES_SOCKET_API	This is macro NET_PRES_SOCKET_API.
NET_PRES_TRANSPORT_API_H	This is macro NET_PRES_TRANSPORT_API_H.
NET_PRES_H	This is macro NET_PRES_H.
NET_PRES_EncProviderReadReady	Defines the read ready function to the provider
NET_PRES_EncProviderWriteReady	Defines the write ready function to the provider.
NET_PRES_TransIsPortDefaultSecured	Checks to see if a port is encrypted by default.
NET_PRES_EncProviderMaxOutputSize	Defines the maximum output size function to the provider.
NET_PRES_EncProviderOutputSize	Defines the output size function to the provider.