API: csIMalloc

Allocates and frees memory.

Methods

The csIMalloc interface implements six methods:

Method: Calloc	Allocates and initializes memory for a number of objects.
Method: Free	Frees memory that is no longer in use.
Method: FreeIf	Frees memory, allowing a NULL pointer.
Init	Confirms that the interface was found and registered.
Method: Malloc	Allocates an amount of memory.
Method: Realloc	Reallocates previously allocated memory.

Description

Plug-in modules can use this object to take advantage of the server’s efficient memory allocation technique. The object is valid for the full lifetime of the client, so Init does not return a reference.

Method: Calloc

Purpose

Allocates, and initializes to zero, memory for a number of objects.

Syntax

void* Calloc (PRUint32 aSize, PPRUint32 aNum)=0;

Parameters

The method has the following two parameters:

aSize	The size in bytes of each object.
nNum	The number of objects.

Returns

A pointer to the allocated memory on success, or NULL on failure.

Description

This method allocates enough memory for the specified number of objects of the specified size, and initializes the memory to zero.

Method: Free

Purpose

Free memory previously allocated by the Malloc method.

Syntax

PRUint32 Free (void * aPtr)=0;

Parameters

The method has the following parameter:

aPtr	A pointer to the memory to be freed.

Returns

NS_OK on success, non-zero error code on failure.

Description

Use this method in the same way as its C or C++ counterpart to free previously allocated memory.

Method: FreeIf

Purpose

Free memory previously allocated by the Malloc method, allowing a NULL pointer.

Syntax

PRUint32 FreeIf (void * aPtr)=0;

Parameters

The method has the following parameter:

aPtr	A pointer to the memory to be freed or NULL.

Returns

NS_OK on success, non-zero error code on failure.

Description

Frees the memory at the specified location, if aPtr is not NULL.

Init

Purpose

Confirm that the interface has been registered.

Syntax

PRUint32 Init() = 0;

Parameters

The method has no parameters.

Returns

NS_OK on success, non-zero error code on failure.

Description

The server calls this method to confirm that the interface was found and registered successfully.

Method: Malloc

Purpose

Allocate a specified amount of memory.

Syntax

void* Malloc (PRUint32 nBytes)=0;

Parameters

The method has the following parameter:

nBytes

The size in bytes of the memory to be allocated.

Returns

A pointer to the allocated memory on success, or NULL on failure.

Description

Use this method in the same way as its C or C++ counterpart.

Method: Realloc

Purpose

Reallocates memory that was previously allocated.

Syntax

void* Realloc (void* aPtr,PRUint32 nBytes)=0;

Parameters

The method has the following parameter:

aPtr	A pointer to previously allocated memory.
nBytes	The size in bytes of the memory to be allocated.

Returns

A pointer to the allocated memory on success, or NULL on failure.

Description

Use this method in the same way as its C or C++ counterpart to reallocate memory that was previously allocated.