Package ghidra.program.model.data

Class StringDataInstance

  • Direct Known Subclasses:
    StringDataInstance.StaticStringInstance
    public class StringDataInstance
extends java.lang.Object
    Represents an instance of a string in a MemBuffer.

    This class handles all the details of detecting a terminated string's length, converting the bytes in the membuffer into a java native String, and converting the raw String into a formatted human-readable version, according to the various SettingsDefinitions attached to the string data location.

    • Constructor Detail

      • StringDataInstance

        protected StringDataInstance()

      • StringDataInstance

        public StringDataInstance​(DataType dataType,
                          Settings settings,
                          MemBuffer buf,
                          int length)
        Creates a string instance using the data in the MemBuffer and the settings pulled from the string data type.
        Parameters:
        stringDataType - AbstractStringDataType common string base data type.
        settings - Settings attached to the data location.
        buf - MemBuffer containing the data.
        length - Length passed from the caller to the datatype. -1 indicates a 'probe' trying to detect the length of an unknown string, otherwise it will be the length of the containing field of the data instance.

    • Method Detail

      • isString

        public static boolean isString​(Data data)
        Returns true if the Data instance is a 'string'.
        Parameters:
        data - Data instance to test, null ok.
        Returns:
        boolean true if string data.

      • isChar

        public static boolean isChar​(Data data)

      • getCharsetName

        public java.lang.String getCharsetName()
        Returns the string name of the charset.
        Returns:
        string charset name

      • getAddress

        public Address getAddress()
        Returns the address of the MemBuffer.
        Returns:
        Address of the MemBuffer.

      • isPascal

        public boolean isPascal()

      • getDataLength

        public int getDataLength()
        Returns the length of this string's data, in bytes.
        Returns:
        number of bytes in this string.

      • getStringLength

        public int getStringLength()
        Returns the length, in bytes, of the string data object contained in the MemBuffer, or -1 if the length could not be determined.

        This is not the same as the number of characters in the string, or the number of bytes occupied by the characters. For instance, pascal strings have a 1 or 2 byte length field that increases the size of the string data object beyond the characters in the string, and null terminated strings have don't include the null character, but its presence is included in the size of the string object.

        For length-specified string data types that do not use null-terminators and with a known data instance length (ie. not a probe), this method just returns the value specified in the constructor length parameter, otherwise a null-terminator is searched for.

        When searching for a null-terminator, the constructor length parameter will be respected or ignored depending on the StringLayoutEnum.

        When the length parameter is ignored (ie. "unbounded" searching), the search is limited to MAX_STRING_LENGTH bytes.

        The MemBuffer's endian'ness is used to determine which end of the padded character field contains our n-bit character which will be tested for null-ness. (not the endian'ness of the character set name - ie. "UTF-16BE")

        Returns:
        length of the string (NOT including null term if null term probe), in bytes, or -1 if no terminator found.

      • hasNullTerminator

        public boolean hasNullTerminator()
        Returns true if the string has a trailing NULL character within the data instance's bounds.
        Returns:
        boolean true if there is a trailing NULL character.

      • getStringValue

        public java.lang.String getStringValue()
        Returns the string contained in the specified MemBuffer, or null if all the bytes of the string could not be read.

        This method deals in characters of size charSize, that might be padded to a larger size. The raw n-byte characters are converted into a Java String using a Java Charset or by using a custom Ghidra conversion. (see convertBytesToStringCustomCharset)

        The MemBuffer's endian'ness is used to determine which end of the padded field contains our charSize character bytes which will be used to create the java String.

        Returns:
        String containing the characters in buf or null if unable to read all length bytes from the membuffer.

      • getStringRepresentation

        public java.lang.String getStringRepresentation()
        Returns a formatted version of the string returned by getStringValue().

        The resulting string will be formatted with quotes around the parts that contain plain ASCII alpha characters (and simple escape sequences), and out-of-range byte-ish values listed as comma separated hex-encoded values:

        Example (quotes are part of result): "Test\tstring",01,02,"Second\npart",00

        Returns:
        formatted String

      • getTranslatedValue

        public java.lang.String getTranslatedValue()
        Returns the value of the stored translated settings string.

        Returns:
        previously translated string.

      • isShowTranslation

        public boolean isShowTranslation()
        Returns true if the user should be shown the translated value of the string instead of the real value.
        Returns:
        boolean true if should show previously translated value.

      • getCharRepresentation

        public java.lang.String getCharRepresentation()
        Convert a char value in memory into its canonical unicode representation, using attached charset and encoding information.

        This implementation treats the char value as a 1 element long string and reuses the string logic to read it from memory using charset info.

        Returns:
        String containing the representation of the single char.

      • getLabel

        public java.lang.String getLabel​(java.lang.String prefixStr,
                                 java.lang.String abbrevPrefixStr,
                                 java.lang.String defaultStr,
                                 DataTypeDisplayOptions options)

      • getOffcutLabelString

        public java.lang.String getOffcutLabelString​(java.lang.String prefixStr,
                                             java.lang.String abbrevPrefixStr,
                                             java.lang.String defaultStr,
                                             DataTypeDisplayOptions options,
                                             int byteOffset)

      • getByteOffcut

        public StringDataInstance getByteOffcut​(int byteOffset)
        Returns a new StringDataInstance that points to the string characters that start at byteOffset from the start of this instance.

        If the requested offset is not valid, the base string instance (itself) will be returned instead of a new instance.

        Parameters:
        byteOffset - number of bytes from start of data instance to start new instance.
        Returns:
        new StringDataInstance, or this if offset not valid.

      • getCharOffcut

        public StringDataInstance getCharOffcut​(int offsetChars)
        Create a new StringDataInstance that points to a portion of this instance, starting at a character offset (whereever that may be) into the data.

        Parameters:
        offsetChars - number of characters from the beginning of the string to start the new StringDataInstance.
        Returns:
        new StringDataInstance pointing to a subset of characters, or the this instance if there was an error.

      • getStringDataTypeGuess

        public DataType getStringDataTypeGuess()
        Maps a StringDataInstance (this type) to the String DataType that best can handle this type of data.

        I dare myself to type Type one more time.

        Returns:
        DataType, defaulting to StringDataType if no direct match found.

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object