ping-react-native

Expose the Internet Control Message Protocol (ICMP) to React Native app natively.
Measure the round-trip time (RTT) by using ICMP echo request packets to the intended destination and iterate it in native side.

🚀 This library is supported in New Architecture (Turbo Modules)

• Platforms
• Requirements
• Installation
• APIs
  • ICMP
  • useICMP
  • getHostname()
  • getHostAddress()
• Definitions
  • ICMPResult
  • ICMPConstructorData
  • UseICMP
  • UseICMPProps
  • ICMPStatus
• Migrating V1 to V2
• Android Emulator Limitations

Platforms

| Platform | Compatible | Remarks | | -------- | ---------- | ---------------------------------------------------- | | Android | ✅ | | | iOS | ✅ | | | Windows | ❌ | | macOS | ✅ | | | Web | ❌ | There is no ICMP in the web |

Requirements

This library requires explicit library and React Native version due to Turbo Modules capabilities and backward compatibility support

New Architecture

This library requires React Native >= 0.76 version. If you are using the latest React Native, you're good to go. Otherwise, either you need to upgrade your React Native version or you can opt-out the new architecture of your app and see the Old Architecture.

Old Architecture

This library marked for React Native >= 0.76 as the peerDependencies, but actually you can use this library if you're in React Native >= 0.72 version. You need to override this library's peer dependency by adding overrides property of your package.json

{
  "name": "yourapp",
  "private": true
  "dependencies": {
    "ping-react-native": "libraryVersion"
  },
  "overrides": {
    "ping-react-native": {
      "react-native": ">=0.72"
    }
  }
}

Cannot guarantee for older React Native versions support. It requires some tests.

Installation

npm

npm install ping-react-native

or with Yarn

yarn add ping-react-native

APIs

ICMP

A bare JavaScript class to use ICMP controller of native module

import { useRef } from 'react'
import { Button } from 'react-native'

import {
    ICMP,
    type ICMPResult,
} from 'ping-react-native'

export default function App(): React.JSX.Element {
    const
        icmp =
            useRef<ICMP | null>(
                new ICMP({ host: '1.1.1.1', packetSize: 64, timeout: 1000, count: 3 })
            ),

        [result, setResult] =
            useState<ICMPResult | null>(null)

    useEffect(() => {
        const icmpRef = icmp.current
        return () => {
            icmpRef?.stop()
        }
    }, [])

    const onPress = async () => {
        icmp.current?.stop() // Stop previous runner if any
        icmp.current?.ping(res => {
            setResult({
                rtt: result.rtt,
                ttl: result.ttl,
                status: result.status,
                isEnded: result.isEnded,
            })
        })
    }

    return (
        <Button
            title="Ping"
            onPress={ onPress } 
        />
    )
}

References

- Constructors: (data: ICMPConstructorData)

| Data Properties | Type | Required | Default Value | Remarks | | --------------- | --------------------------------- | --------- | ------------- | ---------------------------------------------------------------------------------- | | host | string | Yes | | valid host, e.g. 1.1.1.1 or guthib.com. Invalid host or unknown service will return ping result with ICMPStatus.UNKNOWN_HOST status | | packetSize | number | null | undefined | No | 56 | in bytes | | timeout | number | null | undefined | No | 1000 | in milliseconds | | ttl | number | null | undefined | No | 54 | time-to-live | | count | number | null | undefined | No | 0 | amount of try to ping. 0 is infinite count. Remember to stop the ping before unmounting your component | | interval | number | null | undefined | No | 1000 | in milliseconds

- Methods

| Method | Return | Remarks | | ------------ | ------ | --------------------------------------------------------------------------------------------------------------------- | | ping | void | Run the ICMP ping with arguments that has been defined from constructor. This method is an event listener that will invoke your callback function. If the method is invoked again while the previous process is still running, it will invoke your callback with ICMPStatus.ECHOING status. | | stop | void | Stop current ICMP ping request. It's important to invoke this function to cleanup ICMP request to avoid memory leaks. It's safe to invoke this method even if there is no ping requests are running. |

- Properties

| Property | Type | | ------------------- | ------------------------- | | host | readonly string | | packetSize | readonly number | | timeout | readonly number | | ttl | readonly number | | count | readonly number | | interval | readonly number |

- Static Members

| Static Member | Type | Value | Remarks | | ------------------- | ----------------- | ----------------- | ----------------------------------------------------------------------------------------------------------- | | NO_ECHO_RTT | number | -1 | Just an constant whenever the status of ping result is not ICMPStatus.ECHO. It is used in the rtt result. | | NO_ECHO_TTL | number | -1 | Just an constant whenever the status of ping result is not ICMPStatus.ECHO. It is used in the ttl result. | | Status | enum | ICMPStatus | See ICMPStatus. |

:warning::warning::warning: Important!

IT'S NOT SAFE to unmount your component without invoke the stop method if there are ICMP requests that still running. Your app may still has ICMP requests that still running in the background. Consider to use useICMP hook that do the cleanup automatically.

Do not iterate the ping method like with setInterval unless you really need it. The count argument is the iteration that has been done in native side.

useICMP

A React hook of encapsulated ICMP class that you may use it to simplify the cleanup handling

import {
    useICMP,
} from 'ping-react-native'

export default function App(): React.JSX.Element {
    const { isRunning, result } = useICMP({
        host: 'guthib.com',
        packetSize: 64,
        timeout: 1000,
        interval: 1000,
        count: 10,
        // enabled: false // It's enabled by default. You can control when the ICMP should run
    })

    useEffect(() => {
        if(result) {
            console.log('Result: ', result.rtt, result.ttl, result.status)
        }
    }, [result])
}

You can see full example at /examples/shared/src/screens/test-use-icmp/Page.tsx

It's safe to unmount your component if the subsequent ICMP request is still running. This hook will do the cleanup automatically.

References

- Returns: UseICMP

| Properties | Type | Remarks | | ------------- | ------------- | ---------------------------------------------------------------------------------- | | isRunning | boolean | | result | object | See ICMPResult

getHostname

(host: string) => Promise<string | null>

Gets the host name from an IP address.

If the host argument was given with a host name, a reverse name lookup still will be performed and the result will be returned based on the system configured name lookup service.

The Promise will never be rejected. It will return null if it fails.

getHostAddress

(host: string) => Promise<string | null>

Gets the host address from a host name. Returns the IP address string in textual presentation.

The Promise will never be rejected. It will return null if it fails.

Definitions

ICMPResult

| Properties | Type | Remarks | | ------------- | --------------------------------- | ---------------------------------------------------------------------------------- | | rtt | number | When the status is not ICMPStatus.ECHO, the value will be -1 (NO_ECHO_RTT) | ttl | number | When the status is not ICMPStatus.ECHO, the value will be -1 (NO_ECHO_TTL) | status | enum | See ICMPStatus. | isEnded | boolean | true if there is no subsequent ping requests.

ICMPConstructorData

| Properties | Type | Remarks | | ------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------- | | host | string | Can either be a machine name, such as "guthib.com", or a textual representation of its IP address. | | packetSize | number | null | undefined | Value in bytes. If it smaller than zero, the promise result will be returned with ICMPStatus.INVALID_ARG status. | ttl | number | null | undefined | time-to-live | timeout | number | null | undefined | Value in milliseconds. | count | number | null | undefined | Amount of try to ping. 0 is infinite count | interval | number | null | undefined | Value in milliseconds.

UseICMP

| Properties | Type | Remarks | | ------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------- | | isRunning | boolean | A React state. false if there is no subsequent ping requests | | result | object | undefined | See ICMPResult

UseICMPProps

It extends ICMPConstructorData

| Properties | Type | Remarks | | ------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------- | | enabled | boolean | undefined | Default is true if the property is undefined

ICMPStatus

| Member | Value | Remarks | | ------------------------------ | -------------- | ------------------------------------------------------------------------------------ | | ECHO | 2 | Success | ECHOING | 1 | When the ping method is invoked when the previous process still running | TIMEDOUT | 0 | | INVALID_ARG | -1 | Invalid argument. such as illegal packet size, ttl out of range. | UNKNOWN_HOST | -2 | | UNKNOWN_FAILURE | -3 |

Migrating V1 to V2

There is breaking change 2.x version. See migration guide.

Android Emulator Limitations

Depending on the environment, the emulator might not be able to support ICMP. See Local networking limitations.

Instead, you can use Android physical device and run React Native app in it.