Skip to content

Latest commit

 

History

History
330 lines (215 loc) · 7.24 KB

chapter4.adoc

File metadata and controls

330 lines (215 loc) · 7.24 KB

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

Allowed From

Application code

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

Allowed From

Application code

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).

Input Parameters

  • nat_ptr: Pointer to NAT instance

Return Values

  • NX_SUCCESS (0x00) NAT successfully enabled

  • NX_PTR_ERROR (0x07) Invalid input pointer parameter

Allowed From

Application code

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.

Input Parameters

  • nat_ptr: Pointer to NAT instance

Return Values

  • NX_SUCCESS (0x00) NAT successfully disabled

  • NX_PTR_ERROR (0x07) Invalid input pointer parameter

Allowed From

Application code

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

Allowed From

Application code

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);

Description

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. */