Gnet Network Library Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# Internet address module

## Name

Internet address module -- Internet address functions.

## Synopsis

    GInetAddr*  gnet_inetaddr_new               (const gchar *name,
                                                 const gint port);
    GInetAddrNewAsyncID gnet_inetaddr_new_async (const gchar *name,
                                                 const gint port,
                                                 GInetAddrNewAsyncFunc func,
                                                 gpointer data);
    void        gnet_inetaddr_new_async_cancel  (GInetAddrNewAsyncID id);
    typedef     GInetAddrNewAsyncID;
    void        (*GInetAddrNewAsyncFunc)        (GInetAddr *inetaddr,
                                                 GInetAddrAsyncStatus status,
                                                 gpointer data);
    enum        GInetAddrAsyncStatus;
    GInetAddr*  gnet_inetaddr_clone             (const GInetAddr *ia);
    void        gnet_inetaddr_delete            (GInetAddr *ia);
    void        gnet_inetaddr_ref               (GInetAddr *ia);
    void        gnet_inetaddr_unref             (GInetAddr *ia);
    gchar*      gnet_inetaddr_get_name          (GInetAddr *ia);
    GInetAddrGetNameAsyncID gnet_inetaddr_get_name_async
                                                (GInetAddr *ia,
                                                 GInetAddrGetNameAsyncFunc func,
                                                 gpointer data);
    void        gnet_inetaddr_get_name_async_cancel
                                                (GInetAddrGetNameAsyncID id);
    typedef     GInetAddrGetNameAsyncID;
    void        (*GInetAddrGetNameAsyncFunc)    (GInetAddr *inetaddr,
                                                 GInetAddrAsyncStatus status,
                                                 gchar *name,
                                                 gpointer data);
    gchar*      gnet_inetaddr_get_canonical_name
                                                (GInetAddr *ia);
    gint        gnet_inetaddr_get_port          (const GInetAddr *ia);
    void        gnet_inetaddr_set_port          (const GInetAddr *ia,
                                                 guint port);
    gchar*      gnet_inetaddr_gethostname       (void);
    GInetAddr*  gnet_inetaddr_gethostaddr       (void);
    guint       gnet_inetaddr_hash              (const gpointer p);
    gint        gnet_inetaddr_equal             (const gpointer p1,
                                                 const gpointer p2);
    gint        gnet_inetaddr_noport_equal      (const gpointer p1,
                                                 const gpointer p2);

## Description

InetAddr represents an internet address. Currently, only IP version 4 addresses are used (eg, addresses in the form 141.213.8.59).

## Details

### gnet_inetaddr_new ()

    GInetAddr*  gnet_inetaddr_new               (const gchar *name,
                                                 const gint port);

Create an internet address from a name and port.

`name` : | a nice name (eg, mofo.eecs.umich.edu) or a dotted decimal name (eg, 141.213.8.59). You can delete the after the function is called.
`port` : | port number (0 if the port doesn't matter)
Returns : | a new InetAddr, or NULL if there was a failure.

### gnet_inetaddr_new_async ()

    GInetAddrNewAsyncID gnet_inetaddr_new_async (const gchar *name,
                                                 const gint port,
                                                 GInetAddrNewAsyncFunc func,
                                                 gpointer data);

Create a GInetAddr from a name and port asynchronously. Once the structure is created, it will call the callback. It may call the callback before the function returns. It will call the callback if there is a failure.

The Unix version forks and does the lookup, which can cause some problems. In general, this will work ok for most programs most of the time. It will be slow or even fail when using operating systems that copy the entire process when forking.

If you need to lookup a lot of addresses, we recommend calling g_main_iteration(FALSE) between calls. This will help prevent an explosion of processes.

If you need a more robust library for Unix, look at <ulink url="http://www.gnu.org/software/adns/adns.html">GNU ADNS</ulink>. GNU ADNS is under the GNU GPL.

The Windows version should work fine. Windows has an asynchronous DNS lookup function.

`name` : | a nice name (eg, mofo.eecs.umich.edu) or a dotted decimal name (eg, 141.213.8.59). You can delete the after the function is called.
`port` : | port number (0 if the port doesn't matter)
`func` : | Callback function.
`data` : | User data passed when callback function is called.
Returns : | ID of the lookup which can be used with gnet_inetaddr_new_async_cancel() to cancel it; NULL on immediate success or failure.

### gnet_inetaddr_new_async_cancel ()

    void        gnet_inetaddr_new_async_cancel  (GInetAddrNewAsyncID id);

Cancel an asynchronous GInetAddr creation that was started with gnet_inetaddr_new_async().

`id` : | ID of the lookup

### GInetAddrNewAsyncID

    typedef gpointer GInetAddrNewAsyncID;

### GInetAddrNewAsyncFunc ()

    void        (*GInetAddrNewAsyncFunc)        (GInetAddr *inetaddr,
                                                 GInetAddrAsyncStatus status,
                                                 gpointer data);

`inetaddr` : |
`status` : |
`data` : |

### enum GInetAddrAsyncStatus

    typedef enum {
      GINETADDR_ASYNC_STATUS_OK,
      GINETADDR_ASYNC_STATUS_ERROR
    } GInetAddrAsyncStatus;

### gnet_inetaddr_clone ()

    GInetAddr*  gnet_inetaddr_clone             (const GInetAddr *ia);

Create an internet address from another one.

`ia` : | Address to clone
Returns : | a new InetAddr, or NULL if there was a failure.

### gnet_inetaddr_delete ()

    void        gnet_inetaddr_delete            (GInetAddr *ia);

Delete a GInetAddr.

`ia` : | GInetAddr to delete

### gnet_inetaddr_ref ()

    void        gnet_inetaddr_ref               (GInetAddr *ia);

Increment the reference counter of the GInetAddr.

`ia` : | GInetAddr to reference

### gnet_inetaddr_unref ()

    void        gnet_inetaddr_unref             (GInetAddr *ia);

Remove a reference from the GInetAddr. When reference count reaches 0, the address is deleted.

`ia` : | GInetAddr to unreference

### gnet_inetaddr_get_name ()

    gchar*      gnet_inetaddr_get_name          (GInetAddr *ia);

Get the nice name of the address (eg, "mofo.eecs.umich.edu"). Be warned that this call may block since it may need to do a reverse DNS lookup.

`ia` : | Address to get the name of.
Returns : | NULL if there was an error. The caller is responsible for deleting the returned string.

### gnet_inetaddr_get_name_async ()

    GInetAddrGetNameAsyncID gnet_inetaddr_get_name_async
                                                (GInetAddr *ia,
                                                 GInetAddrGetNameAsyncFunc func,
                                                 gpointer data);

Get the nice name of the address (eg, "mofo.eecs.umich.edu"). This function will use the callback once it knows the nice name. It may even call the callback before it returns. The callback will be called if there is an error.

The Unix version forks and does the reverse lookup. This has problems. See the notes for gnet_inetaddr_new_async(). The Windows version should work fine.

`ia` : | Address to get the name of.
`func` : | Callback function.
`data` : | User data passed when callback function is called.
Returns : | ID of the lookup which can be used with gnet_inetaddrr_get_name_async_cancel() to cancel it; NULL on immediate success or failure.

### gnet_inetaddr_get_name_async_cancel ()

    void        gnet_inetaddr_get_name_async_cancel
                                                (GInetAddrGetNameAsyncID id);

Cancel an asynchronous nice name lookup that was started with gnet_inetaddr_get_name_async().

`id` : | ID of the lookup

### GInetAddrGetNameAsyncID

    typedef gpointer GInetAddrGetNameAsyncID;

### GInetAddrGetNameAsyncFunc ()

    void        (*GInetAddrGetNameAsyncFunc)    (GInetAddr *inetaddr,
                                                 GInetAddrAsyncStatus status,
                                                 gchar *name,
                                                 gpointer data);

`inetaddr` : |
`status` : |
`name` : |
`data` : |

### gnet_inetaddr_get_canonical_name ()

    gchar*      gnet_inetaddr_get_canonical_name
                                                (GInetAddr *ia);

Get the "canonical" name of an address (eg, for IP4 the dotted decimal name 141.213.8.59).

`ia` : | Address to get the canonical name of.
Returns : | NULL if there was an error. The caller is responsible for deleting the returned string.

### gnet_inetaddr_get_port ()

    gint        gnet_inetaddr_get_port          (const GInetAddr *ia);

Get the port number.

`ia` : | Address to get the port number of.
Returns : | the port number.

### gnet_inetaddr_set_port ()

    void        gnet_inetaddr_set_port          (const GInetAddr *ia,
                                                 guint port);

Set the port number.

`ia` : | Address to set the port number of.
`port` : | New port number

### gnet_inetaddr_gethostname ()

    gchar*      gnet_inetaddr_gethostname       (void);

Get the primary host's name.

Returns : | the name of the host; NULL if there was an error. The caller is responsible for deleting the returned string.

### gnet_inetaddr_gethostaddr ()

    GInetAddr*  gnet_inetaddr_gethostaddr       (void);

Get the primary host's GInetAddr.

Returns : | the GInetAddr of the host; NULL if there was an error. The caller is responsible for deleting the returned GInetAddr.

### gnet_inetaddr_hash ()

    guint       gnet_inetaddr_hash              (const gpointer p);

Hash the address. This is useful for glib containers.

`p` : | Pointer to an GInetAddr.
Returns : | hash value.

### gnet_inetaddr_equal ()

    gint        gnet_inetaddr_equal             (const gpointer p1,
                                                 const gpointer p2);

Compare two GInetAddr's.

`p1` : | Pointer to first GInetAddr.
`p2` : | Pointer to second GInetAddr.
Returns : | 1 if they are the same; 0 otherwise.

### gnet_inetaddr_noport_equal ()

    gint        gnet_inetaddr_noport_equal      (const gpointer p1,
                                                 const gpointer p2);

Compare two GInetAddr's, but does not compare the port numbers.

`p1` : | Pointer to first GInetAddr.
`p2` : | Pointer to second GInetAddr.
Returns : | 1 if they are the same; 0 otherwise.

<<< Previous Page | Home | Up | Next Page >>>
GNet main module | Multicast module