Chapter 4 - Description of NAT services

This chapter contains a description of all NetX Duo NAT API services (listed below) in alphabetical order.

Note: In the Return Values section in the following API descriptions, values in BOLD are not affected by the NX_DISABLE_ERROR_CHECKING define that is used to disable API error checking, while non-bold values are completely disabled.

nx_nat_create

Create a NAT Server

Prototype

UINT nx_nat_create(
    NX_NAT_DEVICE *nat_ptr,
    NX_IP *ip_ptr,
    UINT global_interface_index,
    VOID *dynamic_cache_memory,
    UINT dynamic_cache_size);

Description

This service creates an instance of the NAT server.

Input Parameters

nat_ptr: Pointer to NAT instance to create
ip_ptr Pointer: to IP instance
global_interface_index: Index to the global network interface
dynamic_cache_memory: Pointer memory area to NAT table
dynamic_cache_size: Size of memory area for NAT table

Return Values

NX_SUCCESS (0x00) NAT server successfully created
NX_PTR_ERROR (0x07) Invalid input pointer parameter
NX_NAT_PARAM_ERROR (0xD01) Invalid non pointer input
NX_NAT_CACHE_ERROR (0xD02) Invalid cache pointer input

Example

#define NX_NAT_ENTRY_CACHE_SIZE 20480

static UCHAR nat_cache[NX_NAT_ENTRY_CACHE_SIZE];
UINT global_interface_index = 0;

/* Create a NAT Server and cache with a global interface index. */
status = nx_nat_create(nat_ptr, ip_ptr, global_interface_index,
    nat_cache, NX_NAT_ENTRY_CACHE_SIZE);

/* If status = NX_SUCCESS, the NAT instance was successfully
    created. */

nx_nat_delete

Delete a NAT Server

Prototype

UINT nx_nat_delete(NX_NAT_DEVICE *nat_ptr);

Description

This service deletes a previously created NAT Server.

Input Parameters

nat_ptr: Pointer to NAT instance to delete

Return Values

NX_SUCCESS (0x00) NAT successfully deleted
NX_PTR_ERROR (0x07) Invalid input pointer parameter

Example

/* Delete the NAT instance. */
status = nx_nat_delete (nat_ptr);

/* If the NAT instance was successfully deleted, status = NX_SUCCESS. */

nx_nat_enable

Enable the IP instance for NAT

Prototype

UINT nx_nat_enable(NX_NAT_DEVICE *nat_ptr);

Description

This service enables the IP instance for NAT (e.g. forward received packets to the NAT server).

Return Values

NX_SUCCESS (0x00) NAT successfully enabled
NX_PTR_ERROR (0x07) Invalid input pointer parameter

Example

/* Enable the NAT server. */
status = nx_nat_enable (nat_ptr);

/* If status = NX_SUCCESS, the IP instance was successfully enabled for NAT. */

nx_nat_disable

Disable the IP instance for NAT

Prototype

UINT nx_nat_disable(NX_NAT_DEVICE *nat_ptr);

Description

This service disables NAT on the IP instance.

Return Values

NX_SUCCESS (0x00) NAT successfully disabled
NX_PTR_ERROR (0x07) Invalid input pointer parameter

Example

/* Disable the NAT server. */
status = nx_nat_disable (nat_ptr);

/* If status = NX_SUCCESS the NAT operation successfully disable. */

nx_nat_cache_notify_set

Set a cache full notify callback function

Prototype

UINT nx_nat_cache_notify_set(
    NX_NAT_DEVICE *nat_ptr,
    VOID (*cache_full_notify_cb)(NX_NAT_DEVICE *nat_ptr)));

Description

This service registers the cache full callback with the input function pointer cache_full_notify_cb which points to a user defined cache full notify function.

Input Parameters

nat_ptr: Pointer to NAT instance
cache_full_notify_cb: Pointer to cache full notify function

Return Values

NX_SUCCESS (0x00) Cache full notify function successfully set
NX_PTR_ERROR (0x07) Invalid input pointer parameter
NX_NAT_PARAM_ERROR (0xD01) Invalid non pointer input

Example

/* Set the cache full notify callback function to the NAT instance. */
status = nx_nat_cache_notify_set(nat_ptr, cache_full_notify_cb);

/* If status = NX_SUCCESS the callback function was successfully set. */

nx_nat_inbound_entry_create

Create an inbound entry in the NAT translation table

Prototype

UINT nx_nat_inbound_entry_create(
    NX_NAT_DEVICE *nat_ptr,
    NX_NAT_TRANSLATION_ENTRY *entry_ptr
    ULONG local_ip_address,
    USHORT external_port,
    USHORT local_port,
    UCHAR protocol);

This service creates an inbound entry as static (permanent entry, never expires) and adds it to the NAT translation table. These entries are usually created for local host servers where a connection is initiated from a host on the outside network. The NAT server checks that the external port is not already in use in the translation table or bound by a previously existing NetX Duo socket of the same protocol.

Input Parameters

nat_ptr: Pointer to NAT instance
entry_ptr: Pointer to translation entry
local_ip_address: Local host IP address
external_port: Destination port on the external network
local_port: Source (local host) port
protocol: Packet protocol (e.g TCP)

Return Values

NX_SUCCESS (0x00) Entry successfully created
NX_NAT_PORT_UNAVAILABLE (0xD0D) Invalid external port
NX_PTR_ERROR (0x07) Invalid input pointer parameter
NX_NAT_PARAM_ERROR (0xD01) Invalid non pointer input

Allowed From

Application code

Example

/* Create an entry for an inbound TCP packet. */
status = nx_nat_inbound_entry_create(nat_ptr, entry_ptr,
    IP_ADDRESS(192,168,2,2), 5001, 5001,
    NX_PROTOCOL_TCP);

/* If status = NX_SUCCESS the entry was successfully created. */

nx_nat_inbound_entry_delete

Delete an inbound entry in the NAT translation table

Prototype

UINT nx_nat_inbound_entry_delete(
    NX_NAT_DEVICE *nat_ptr,
    NX_NAT_TRANSLATION_ENTRY *delete_entry_ptr)

Description

This service deletes the specified inbound entry from the translation table.

Input Parameters

nat_ptr: Pointer to NAT instance
delete_entry_ptr: Pointer to the NAT translation entry

Return Values

NX_SUCCESS (0x00) Entry successfully deleted
NX_NAT_ENTRY_NOT_FOUND (0xD04) Entry does not found
NX_PTR_ERROR (0x07) Invalid input pointer parameter
NX_NAT_ENTRY_TYPE_ERROR (0xD0C) Invalid translation type

Allowed From

Application code

Example

/* Delete the specified static entry from the translation table. */
status = nx_nat_inbound_entry_delete(nat_ptr, delete_entry_ptr);

/* If status = NX_SUCCESS the entry was successfully deleted. */