Signature.java
/*
** Module : Signature.java
** Abstract : contains descriptors for a native function's args and return value
**
** Copyright (c) 2013-2018, Golden Code Development Corporation.
**
** -#- -I- --Date-- ---------------------------------Description---------------------------------
** 001 GES 20130109 First version.
** 003 CA 20181029 CALL handle's DLL-CALL-TYPE has a quirk where the native API is not invoked,
** just resolved - added the Signature.noInvoke to help with this.
*/
/*
** This program is free software: you can redistribute it and/or modify
** it under the terms of the GNU Affero General Public License as
** published by the Free Software Foundation, either version 3 of the
** License, or (at your option) any later version.
**
** This program is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
** GNU Affero General Public License for more details.
**
** You may find a copy of the GNU Affero GPL version 3 at the following
** location: https://www.gnu.org/licenses/agpl-3.0.en.html
**
** Additional terms under GNU Affero GPL version 3 section 7:
**
** Under Section 7 of the GNU Affero GPL version 3, the following additional
** terms apply to the works covered under the License. These additional terms
** are non-permissive additional terms allowed under Section 7 of the GNU
** Affero GPL version 3 and may not be removed by you.
**
** 0. Attribution Requirement.
**
** You must preserve all legal notices or author attributions in the covered
** work or Appropriate Legal Notices displayed by works containing the covered
** work. You may not remove from the covered work any author or developer
** credit already included within the covered work.
**
** 1. No License To Use Trademarks.
**
** This license does not grant any license or rights to use the trademarks
** Golden Code, FWD, any Golden Code or FWD logo, or any other trademarks
** of Golden Code Development Corporation. You are not authorized to use the
** name Golden Code, FWD, or the names of any author or contributor, for
** publicity purposes without written authorization.
**
** 2. No Misrepresentation of Affiliation.
**
** You may not represent yourself as Golden Code Development Corporation or FWD.
**
** You may not represent yourself for publicity purposes as associated with
** Golden Code Development Corporation, FWD, or any author or contributor to
** the covered work, without written authorization.
**
** 3. No Misrepresentation of Source or Origin.
**
** You may not represent the covered work as solely your work. All modified
** versions of the covered work must be marked in a reasonable way to make it
** clear that the modified work is not originating from Golden Code Development
** Corporation or FWD. All modified versions must contain the notices of
** attribution required in this license.
*/
package com.goldencode.p2j.library;
import java.io.*;
/**
* Container for all info related to a native function's arguments and return value.
*/
public class Signature
implements Externalizable
{
/** Argument list in left to right order, with one element for each argument. */
private BaseNativeType[] args = null;
/** Return value (will not be <code>null</code> if the function returns a value). */
private BaseNativeType retval = null;
/** The platform type on which the client code is running. */
private int platform = 0;
/** If not {@link LibraryManager#ERROR_NONE}, then this code describes the failure. */
private int error = LibraryManager.ERROR_NONE;
/** Flag indicating this API will never be invoked, just resolved. */
private boolean noInvoke = false;
/**
* Default constructor.
*/
public Signature()
{
}
/**
* Create a new native function signature.
*
* @param numArgs
* The non-negative number of arguments for the native function.
*
* @throws IllegalArgumentException
* If the number of arguments was specified as a negative number.
*/
public Signature(int numArgs)
{
setArgumentSize(numArgs);
}
/**
* Reports the number of arguments for this native function.
*
* @return The number of arguments (will always be 0 or more).
*/
public int getArgumentSize()
{
return args.length;
}
/**
* Defines the number of arguments for this native function.
*
* @param numArgs
* The number of arguments (must always be 0 or more).
*
* @throws IllegalArgumentException
* If the number of arguments was specified as a negative number.
*/
public void setArgumentSize(int numArgs)
{
if (numArgs < 0)
throw new IllegalArgumentException("Functions cannot have a negative number of arguments!");
args = new BaseNativeType[numArgs];
}
/**
* Obtains a specific argument for this native function.
*
* @param idx
* The 0-based index number of the argument to obtain.
*
* @return The specified argument if it has been already initialized and the index is
* within range. <code>null</code> if the argument has not yet been defined
* but is within the valid range.
*
* @throws IllegalArgumentException
* If the argument index is out of range.
*/
public BaseNativeType getArgument(int idx)
{
if (idx < 0 || idx >= args.length)
throw new IllegalArgumentException("Invalid argument index.");
return args[idx];
}
/**
* Assigns the argument to the given index position for this native function.
*
* @param value
* The argument to assign. If this is <code>null</code>, it effectively clears
* the state for that index position.
* @param idx
* The 0-based index number of the argument to assign.
*
* @throws IllegalArgumentException
* If the argument index is out of range.
*/
public void setArgument(BaseNativeType value, int idx)
{
if (idx < 0 || idx >= args.length)
throw new IllegalArgumentException("Invalid argument index.");
args[idx] = value;
}
/**
* Obtains the descriptor for the return value.
*
* @return The descriptor or <code>null</code> if there is no defined return value.
*/
public BaseNativeType getReturnValue()
{
return retval;
}
/**
* Assigns the descriptor for the return value.
*
* @param retval
* The descriptor to assign. If this is <code>null</code>, it effectively clears
* the state for the return value.
*/
public void setReturnValue(BaseNativeType retval)
{
this.retval = retval;
}
/**
* Obtains the constant that defines the platform type on which the client is running.
*
* @return The client platform type.
*/
public int getPlatform()
{
return platform;
}
/**
* Assigns the constant that defines the platform type on which the client is running.
*
* @param platform
* The new client platform type.
*/
public void setPlatform(int platform)
{
this.platform = platform;
}
/**
* Obtains the constant that defines the error code from the invocation attempt. If this is
* not {@link LibraryManager#ERROR_NONE}, then a failure has occurred and this code describes
* the failure.
*
* @return The error code, if any.
*/
public int getErrorCode()
{
return error;
}
/**
* Assigns the constant that defines the error code from the invocation attempt.
*
* @param error
* The new error code. If this is not {@link LibraryManager#ERROR_NONE}, then a
* failure has occurred and this code describes the failure.
*/
public void setErrorCode(int error)
{
this.error = error;
}
/**
* Get the state of the {@link #noInvoke no-invoke} flag.
*
* @return See above.
*/
public boolean isNoInvoke()
{
return noInvoke;
}
/**
* Set the state of the {@link #noInvoke no-invoke} flag.
*
* @param noInvoke
* The new value of this flag.
*/
public void setNoInvoke(boolean noInvoke)
{
this.noInvoke = noInvoke;
}
/**
* Replacement for the default object reading method. The latest
* state is read from the input source. The parent's state is
* read first.
*
* @param in
* The input source from which fields will be restored.
*
* @throws IOException
* In case of I/O errors.
* @throws ClassNotFoundException
* If payload can't be instantiated.
*/
public void readExternal(ObjectInput in)
throws IOException,
ClassNotFoundException
{
noInvoke = in.readBoolean();
platform = in.readInt();
error = in.readInt();
boolean hasRet = in.readBoolean();
if (hasRet)
retval = (BaseNativeType) in.readObject();
int numArgs = in.readInt();
setArgumentSize(numArgs);
for (int i = 0; i < numArgs; i++)
{
args[i] = (BaseNativeType) in.readObject();
}
}
/**
* Replacement for the default object writing method. The latest
* state is written to the output destination. The parent's state is
* written first.
*
* @param out
* The output destination to which fields will be saved.
*
* @throws IOException
* In case of I/O errors.
*/
public void writeExternal(ObjectOutput out)
throws IOException
{
out.writeBoolean(noInvoke);
out.writeInt(platform);
out.writeInt(error);
boolean hasRet = (retval != null);
out.writeBoolean(hasRet);
if (hasRet)
out.writeObject(retval);
out.writeInt(args.length);
for (int i = 0; i < args.length; i++)
{
out.writeObject(args[i]);
}
}
}